feat: Added @vue-event tag for $emit events (Kocal#174)

The same than Kocal#168, but with 2/3 minors modif.

Close Kocal#160.

Author: Kocal

.eslintrc.json

@@ -29,7 +29,8 @@
         "_isVueDoc",
         "_vueProps",
         "_vueData",
-        "_vueComputed"
+        "_vueComputed",
+        "_vueEvent"
       ]
     }]
   }

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).
 
@@ -56,6 +57,8 @@ All of those tags work the same way than [`@param` tag](http://usejsdoc.org/tags
    * @vue-prop {Number} [step=1] - Step
    * @vue-data {Number} counter - Current counter's value
    * @vue-computed {String} message
+   * @vue-event {Number} increment - Emit counter's value after increment
+   * @vue-event {Number} decrement - Emit counter's value after decrement
    */
   export default {
     props: {
@@ -77,6 +80,16 @@ All of those tags work the same way than [`@param` tag](http://usejsdoc.org/tags
       message() {
         return `Current value is ${this.counter}`;
       }
+    },
+    methods: {
+      increment() {
+        this.counter += 1;
+        this.$emit('increment', this.counter);
+      },
+      decrement() {
+        this.counter -= 1;
+        this.$emit('decrement', this.counter);
+      }
     }
   }
 </script>

__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),
       },

cypress/integration/templates/default.spec.js

@@ -144,28 +144,61 @@ describe('Template: default', () => {
       });
   });
 
+  it('should renders event correctly', () => {
+    const events = [
+      { name: '<code>increment</code>', type: 'Number', description: "Emit counter's value after increment" },
+      { name: '<code>decrement</code>', type: 'Number', description: "Emit counter's value 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(2);
+
+        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');
 
     cy.get('#decrement')
       .contains('decrement()')
       .next('.description')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line53"]', 'line 53');
+      .contains('a[href="better-components_BetterCounter.vue.html#line56"]', 'line 56');
 
     cy.get('#increment')
       .contains('increment()')
       .next('.description')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line46"]', 'line 46');
+      .contains('a[href="better-components_BetterCounter.vue.html#line48"]', 'line 48');
 
     cy.get('#showDialog')
       .contains('showDialog(counter)')
       .next('.description')
       .next('h5')
       .next('.params')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line61"]', 'line 61');
+      .contains('a[href="better-components_BetterCounter.vue.html#line65"]', 'line 65');
 
     cy.contains('created()').should('not.exist');
   });

cypress/integration/templates/docstrap.spec.js

@@ -144,28 +144,61 @@ describe('Template: docstrap', () => {
       });
   });
 
+  it('should renders event correctly', () => {
+    const events = [
+      { name: '<code>increment</code>', type: 'Number', description: "Emit counter's value after increment" },
+      { name: '<code>decrement</code>', type: 'Number', description: "Emit counter's value 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(2);
+
+        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');
     cy.get('#decrement')
       .contains('decrement()')
       .parent()
       .next('dd')
       .find('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-53"]', 'line 53');
+      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-56"]', 'line 56');
 
     cy.get('#increment')
       .contains('increment()')
       .parent()
       .next('dd')
       .find('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-46"]', 'line 46');
+      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-48"]', 'line 48');
 
     cy.get('#showDialog')
       .contains('showDialog(counter)')
       .parent()
       .next('dd')
       .find('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-61"]', 'line 61');
+      .contains('a[href="better-components_BetterCounter.vue.html#sunlight-1-line-65"]', 'line 65');
 
     cy.contains('created()').should('not.exist');
   });

cypress/integration/templates/minami.spec.js

@@ -146,25 +146,58 @@ describe('Template: minami', () => {
       });
   });
 
+  it('should renders event correctly', () => {
+    const events = [
+      { name: '<code>increment</code>', type: 'Number', description: "Emit counter's value after increment" },
+      { name: '<code>decrement</code>', type: 'Number', description: "Emit counter's value 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(2);
+
+        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');
     cy.get('#decrement')
       .contains('decrement()')
       .next('.description')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line53"]', 'line 53');
+      .contains('a[href="better-components_BetterCounter.vue.html#line56"]', 'line 56');
 
     cy.get('#increment')
       .contains('increment()')
       .next('.description')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line46"]', 'line 46');
+      .contains('a[href="better-components_BetterCounter.vue.html#line48"]', 'line 48');
 
     cy.get('#showDialog')
       .contains('showDialog(counter)')
       .next('.description')
       .next('.details')
-      .contains('a[href="better-components_BetterCounter.vue.html#line61"]', 'line 61');
+      .contains('a[href="better-components_BetterCounter.vue.html#line65"]', 'line 65');
 
     cy.contains('created()').should('not.exist');
   });

cypress/integration/templates/tui.spec.js

@@ -148,19 +148,52 @@ describe('Template: tui', () => {
       });
   });
 
+  it('should renders event correctly', () => {
+    const events = [
+      { name: '<code>increment</code>', type: '<span class="param-type">Number</span>', description: "Emit counter's value after increment" },
+      { name: '<code>decrement</code>', type: '<span class="param-type">Number</span>', description: "Emit counter's value 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(2);
+
+        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');
     cy.get('#decrement')
       .contains('decrement()')
-      .contains('a[href="better-components_BetterCounter.vue.html#line53"]', 'line 53');
+      .contains('a[href="better-components_BetterCounter.vue.html#line56"]', 'line 56');
 
     cy.get('#increment')
       .contains('increment()')
-      .contains('a[href="better-components_BetterCounter.vue.html#line46"]', 'line 46');
+      .contains('a[href="better-components_BetterCounter.vue.html#line48"]', 'line 48');
 
     cy.get('#showDialog')
       .contains('showDialog(counter)')
-      .contains('a[href="better-components_BetterCounter.vue.html#line61"]', 'line 61');
+      .contains('a[href="better-components_BetterCounter.vue.html#line65"]', 'line 65');
 
     cy.contains('created()').should('not.exist');
   });

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 counter's value after increment
+   * @vue-event {Number} decrement - Emit counter's value 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);
       },
 
       /**

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);
 };

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,
   );