fix(#61): Parse slot parameters description from comment

KatChaotic · Feb 19, 2021 · c21668e · c21668e
1 parent 62d0fab
commit c21668e
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 9 deletions.
diff --git a/lib/jsdoc.js b/lib/jsdoc.js
@@ -254,6 +254,7 @@ module.exports = {
     parseJSTypeFromValueNode,
 
     convertToJsDocComment,
+    getDefaultJSDocType,
 
     DEFAULT_TYPE
 };
diff --git a/lib/v3/template.js b/lib/v3/template.js
@@ -151,20 +151,24 @@ class TemplateParser extends EventEmitter {
                             .filter(name => name.length > 0 && name !== 'name')
                             .map(name => ({
                                 name: name,
-                                visibility: 'public'
+                                type: jsdoc.getDefaultJSDocType()
                             }));
 
                         const parsedComment = parseAndConsumeLastComment('public');
 
-                        // TODO parse parameters description and types for slot
-
+                        /** @type {import('../../typings').SvelteSlotItem} */
                         const slot = {
                             ...parsedComment,
                             name: attrs.name || 'default',
                             visibility: 'public',
-                            parameters: exposedParameters
+                            params: exposedParameters
                         };
 
+                        parseAndMergeKeywords(parsedComment.keywords, slot, false);
+
+                        // TODO 5.* | Backward compatilibity
+                        slot.parameters = slot.params;
+
                         if (this.includeSourceLocations && parser.startIndex >= 0 && parser.endIndex >= parser.startIndex) {
                             slot.loc = {
                                 start: parser.startIndex,

diff --git a/lib/v3/v3-utils.js b/lib/v3/v3-utils.js
@@ -157,8 +157,9 @@ function updateType(item) {
  *
  * @param {{ name: string; description: string}[]} keywords
  * @param {{ params?: any[]; return?: any }} event
+ * @param {string} [allowToParseReturn=true]
  */
-function parseAndMergeKeywords(keywords = [], event) {
+function parseAndMergeKeywords(keywords = [], event, allowToParseReturn = true) {
     if (!event.params) {
         event.params = [];
     }
@@ -187,7 +188,9 @@ function parseAndMergeKeywords(keywords = [], event) {
                 event.params.push(parsedParam);
             }
         } else if (name in RETURN_ALIASES) {
-            event.return = parseReturnKeyword(description);
+            if (allowToParseReturn) {
+                event.return = parseReturnKeyword(description);
+            }
         }
     });
 

diff --git a/test/svelte3/integration/slots/slot.parameters.svelte b/test/svelte3/integration/slots/slot.parameters.svelte
@@ -1,6 +1,10 @@
 <ul>
     {#each items as item}
         <li>
+            <!--
+                The slot description.
+                @param {string} item The slot parameter description.
+            -->
             <slot name="item" item={item}></slot>
         </li>
     {/each}

diff --git a/test/svelte3/integration/slots/slots.spec.js b/test/svelte3/integration/slots/slots.spec.js
@@ -2,6 +2,7 @@ const path = require('path');
 const chai = require('chai');
 const expect = chai.expect;
 
+const packageConfig = require('../../../../package.json');
 const parser = require('../../../../index');
 
 describe('SvelteDoc v3 - Slots', () => {
@@ -45,7 +46,7 @@ describe('SvelteDoc v3 - Slots', () => {
             expect(slot.name).to.equal('item');
             expect(slot.visibility).to.equal('public');
 
-            const parameters = slot.parameters;
+            const parameters = slot.params;
 
             expect(parameters).to.exist;
             expect(parameters.length).to.equal(1);
@@ -54,7 +55,19 @@ describe('SvelteDoc v3 - Slots', () => {
 
             expect(parameter).to.exist;
             expect(parameter.name).to.equal('item');
-            expect(parameter.visibility).to.equal('public');
+            expect(parameter.description).to.equal('The slot parameter description.');
+            expect(parameter.type).to.deep.eq({
+                kind: 'type',
+                type: 'string',
+                text: 'string'
+            });
+
+            // TODO: 5.* | Backward compatibility test
+            if (packageConfig.version.startsWith('5.')) {
+                expect(slot.parameters, 'parameters field should be removed').undefined;
+            } else {
+                expect(slot.parameters, 'Should be backward compatable until 5.* version').to.deep.eq(slot.params);
+            }
 
             done();
         }).catch(e => {

diff --git a/typings.d.ts b/typings.d.ts
@@ -301,15 +301,38 @@ export interface SvelteEventItem extends ISvelteItem {
  * @since Svelte V3
  * @since {2.0.0}
  */
-export interface SvelteSlotParameter extends ISvelteItem {}
+export interface SvelteSlotParameter {
+    /**
+     * The name of slot parameter.
+     */
+    name: string;
+    /**
+     * The JSDocType of the slot parameter value.
+     * @since {4.1.0}
+     */
+    type: JSDocType;
+    /**
+     * The description of the slot parameter.
+     * @since {4.1.0}
+     */
+    description?: string;
+}
 
 export interface SvelteSlotItem extends ISvelteItem {
     /**
      * List of exposed slot parameters.
      * @since Svelte V3
      * @since {2.0.0}
+     * @deprecated @see params property instead
      */
     parameters?: SvelteSlotParameter[];
+
+    /**
+     * List of exposed slot parameters.
+     * @since Svelte V3
+     * @since {4.1.0}
+     */
+    params?: SvelteSlotParameter[];
 }
 
 export interface SvelteRefItem extends ISvelteItem {