Merge pull request #1 from Kokosso/feature/add_tag_event

Add event tag for jsdoc-vuejs
Kokosso · Jan 8, 2019 · 9410183 · 9410183
2 parents e143554 + eb8ebf0
commit 9410183
Show file tree

Hide file tree

Showing 12 changed files with 155 additions and 6 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -29,7 +29,8 @@
         "_isVueDoc",
         "_vueProps",
         "_vueData",
-        "_vueComputed"
+        "_vueComputed",
+        "_vueEvent"
       ]
     }]
   }

diff --git a/README.md b/README.md
@@ -42,6 +42,7 @@ Update your .vue files with one of the following tags:
 - `@vue-prop`
 - `@vue-data`
 - `@vue-computed`
+- `@vue-event`
 
 All of those tags work the same way than [`@param` tag](http://usejsdoc.org/tags-param.html).
 

diff --git a/__tests__/core/renderer.test.js b/__tests__/core/renderer.test.js
@@ -9,7 +9,9 @@ describe('code.renderer', () => {
   it('should call ejs render method', () => {
     const cb = () => {};
 
-    renderer('my-template', { props: ['props'], data: ['data'], computed: ['computed'] }, cb);
+    renderer('my-template', {
+      props: ['props'], data: ['data'], computed: ['computed'], event: ['event'],
+    }, cb);
 
     expect(ejs.renderFile).toHaveBeenCalledTimes(1);
     expect(ejs.renderFile).toHaveBeenCalledWith(
@@ -18,6 +20,7 @@ describe('code.renderer', () => {
         props: ['props'],
         data: ['data'],
         computed: ['computed'],
+        event: ['event'],
         // an helper function, it should be under keys "utils" or "helpers" btw
         renderType: expect.any(Function),
       },

diff --git a/cypress/integration/templates/default.spec.js b/cypress/integration/templates/default.spec.js
@@ -144,6 +144,39 @@ describe('Template: default', () => {
       });
   });
 
+  it('should renders event correctly', () => {
+    const events = [
+      { name: '<code>increment</code>', type: 'Number', description: 'Emit value of counter after increment' },
+      { name: '<code>decrement</code>', type: 'Number', description: 'Emit value of counter after decrement' },
+    ];
+
+    cy.get('[data-jsdoc-vuejs="section-event"]').contains('Events');
+    cy.get('[data-jsdoc-vuejs="table-event"]').as('table-event');
+
+    cy
+      .get('@table-event')
+      .find('> thead > tr > th')
+      .contains('Name')
+      .next().contains('Payload-type')
+      .next().contains('Description');
+
+    cy
+      .get('@table-event')
+      .find('> tbody > tr')
+      .then(($rows) => {
+        expect($rows).to.have.length(3);
+
+        events.forEach((event, i) => {
+          const $row = $rows.eq(i);
+          const $children = $row.children();
+
+          expect($children.eq(0).html()).to.eq(event.name);
+          expect($children.eq(1).html()).to.eq(event.type);
+          expect($children.eq(2).html()).to.eq(event.description);
+        });
+      });
+  });
+
   it('should render methods properly', () => {
     cy.contains('h3', 'Methods').should('have.attr', 'class', 'subsection-title');
 

diff --git a/example/src/better-components/BetterCounter.vue b/example/src/better-components/BetterCounter.vue
@@ -19,6 +19,8 @@
    * @vue-computed {Array.<String>} fooList - A list of foo
    * @vue-computed {Array.<String>} barList - A list of bar
    * @vue-computed {String} message A message
+   * @vue-event {Number} increment - Emit value of counter after increment
+   * @vue-event {Number} decrement - Emit value of counter after decrement
    */
   export default {
     props: {
@@ -41,17 +43,19 @@
     },
     methods: {
       /**
-       * Increment counter.
+       * Increment counter and emit event 'increment'
        */
       increment() {
         this.counter += this.step;
+        this.$emit('increment', this.counter);
       },
 
       /**
-       * Decrement counter.
+       * Decrement counter and emit event 'decrement'
        */
       decrement() {
         this.counter -= this.step;
+        this.$emit('decrement', this.counter);
       },
 
       /**

diff --git a/index.js b/index.js
@@ -7,6 +7,7 @@ const { isSingleFileComponent, isJSComponent } = require('./lib/core/issers');
 const vueDataTag = require('./lib/tags/vue-data');
 const vuePropTag = require('./lib/tags/vue-prop');
 const vueComputedTag = require('./lib/tags/vue-computed');
+const vueEventTag = require('./lib/tags/vue-event');
 
 // Used to compute good line number for Vue methods
 const exportDefaultLines = {};
@@ -22,7 +23,6 @@ exports.handlers = {
   newDoclet(e) {
     const fileIsSingleFileComponent = isSingleFileComponent(e.doclet);
     const fileIsJSComponent = isJSComponent(e.doclet);
-
     if (!fileIsSingleFileComponent && !fileIsJSComponent) {
       return;
     }
@@ -53,6 +53,7 @@ exports.handlers = {
         props: e.doclet._vueProps || [],
         data: e.doclet._vueData || [],
         computed: e.doclet._vueComputed || [],
+        event: e.doclet._vueEvent || [],
       };
 
       render(template, data, (err, str) => {
@@ -84,4 +85,5 @@ exports.defineTags = function defineTags(dictionary) {
   dictionary.defineTag(vueDataTag.name, vueDataTag.options);
   dictionary.defineTag(vuePropTag.name, vuePropTag.options);
   dictionary.defineTag(vueComputedTag.name, vueComputedTag.options);
+  dictionary.defineTag(vueEventTag.name, vueEventTag.options);
 };
diff --git a/lib/core/renderer.js b/lib/core/renderer.js
@@ -1,14 +1,17 @@
 const ejs = require('ejs');
 const renderType = require('../templates/utils/renderType');
 
-module.exports = function render(template, { props, data, computed }, cb) {
+module.exports = function render(template, {
+  props, data, computed, event,
+}, cb) {
   ejs.renderFile(
     template,
     {
       renderType,
       props,
       data,
       computed,
+      event,
     },
     cb,
   );

diff --git a/lib/tags/vue-event.js b/lib/tags/vue-event.js
@@ -0,0 +1,11 @@
+exports.name = 'vue-event';
+
+exports.options = {
+  canHaveType: true, // type of event-payload
+  canHaveName: true, // name of emitted event
+  onTagged(doclet, tag) {
+    doclet._isVueDoc = true;
+    doclet._vueEvent = doclet._vueEvent || [];
+    doclet._vueEvent.push(tag.value || {});
+  },
+};
diff --git a/lib/templates/default.ejs b/lib/templates/default.ejs
@@ -72,4 +72,27 @@
 </table>
 <% } %>
 
+
+<% if(event.length > 0) { %>
+<h3 class="subsection-title" style="margin-top: 1em" data-jsdoc-vuejs="section-event">Events</h3>
+<table data-jsdoc-vuejs="table-event">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Payload-type</th>
+        <th>Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% event.forEach(function(c) { %>
+    <tr>
+        <td><code><%- c.name %></code></td>
+        <td><%- renderType(c.type) %></td>
+        <td><%- typeof c.description === 'undefined' ? '-' : c.description %></td>
+    </tr>
+    <% }) %>
+    </tbody>
+</table>
+<% } %>
+
 <div class="container-overview"><div><p> <%# Re-open JSDoc template tags %>
diff --git a/lib/templates/docstrap.ejs b/lib/templates/docstrap.ejs
@@ -72,4 +72,26 @@
 </table>
 <% } %>
 
+<% if(event.length > 0) { %>
+<h3 class="subsection-title" style="margin-top: 1em" data-jsdoc-vuejs="section-event">Events</h3>
+<table data-jsdoc-vuejs="table-event">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Payload-type</th>
+        <th>Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% event.forEach(function(c) { %>
+    <tr>
+        <td><code><%- c.name %></code></td>
+        <td><%- renderType(c.type) %></td>
+        <td><%- typeof c.description === 'undefined' ? '-' : c.description %></td>
+    </tr>
+    <% }) %>
+    </tbody>
+</table>
+<% } %>
+
 <div class="container-overview"><div><p> <%# Re-open JSDoc template tags %>
diff --git a/lib/templates/minami.ejs b/lib/templates/minami.ejs
@@ -72,4 +72,26 @@
 </table>
 <% } %>
 
+<% if(event.length > 0) { %>
+<h3 class="subsection-title" style="margin-top: 1em" data-jsdoc-vuejs="section-event">Events</h3>
+<table class="params" data-jsdoc-vuejs="table-event">
+    <thead>
+    <tr>
+        <th>Name</th>
+        <th>Payload-type</th>
+        <th>Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% event.forEach(function(c) { %>
+    <tr>
+        <td><code><%- c.name %></code></td>
+        <td><%- renderType(c.type) %></td>
+        <td><%- typeof c.description === 'undefined' ? '-' : c.description %></td>
+    </tr>
+    <% }) %>
+    </tbody>
+</table>
+<% } %>
+
 <div class="container-overview"><div><p> <%# Re-open JSDoc template tags %>
diff --git a/lib/templates/tui.ejs b/lib/templates/tui.ejs
@@ -91,4 +91,28 @@
 </div>
 <% } %>
 
+<% if(computed.length > 0) { %>
+<h3 class="subsection-title" style="margin-top: 1em" data-jsdoc-vuejs="section-event">Events</h3>
+<div class="container-params">
+    <table class="params" data-jsdoc-vuejs="table-event">
+        <thead>
+        <tr>
+            <th>Name</th>
+            <th>Payload-type</th>
+            <th class="last">Description</th>
+        </tr>
+        </thead>
+        <tbody>
+        <% event.forEach(function(c) { %>
+        <tr>
+            <td class="name"><code><%- c.name %></code></td>
+            <td class="type"><span class="param-type"><%- renderType(c.type) %></span></td>
+            <td class="description last"><%- typeof c.description === 'undefined' ? '-' : c.description %></td>
+        </tr>
+        <% }) %>
+        </tbody>
+    </table>
+</div>
+<% } %>
+
 <div class="container-overview"><div><p> <%# Re-open JSDoc template tags %>