From c21668e93a4b92a9681717b219c43b0698183821 Mon Sep 17 00:00:00 2001
From: "Alexey Mulyukin (alexprey)" <alexprey@yandex.ru>
Date: Fri, 19 Feb 2021 16:18:47 +0300
Subject: [PATCH] fix(#61): Parse slot parameters description from comment

---
 lib/jsdoc.js                                  |  1 +
 lib/v3/template.js                            | 12 ++++++---
 lib/v3/v3-utils.js                            |  7 ++++--
 .../integration/slots/slot.parameters.svelte  |  4 +++
 test/svelte3/integration/slots/slots.spec.js  | 17 +++++++++++--
 typings.d.ts                                  | 25 ++++++++++++++++++-
 6 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/lib/jsdoc.js b/lib/jsdoc.js
index 41434e9..9268203 100644
--- 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
index 359ffb9..e8781ab 100644
--- 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
index 8add384..37b4c5e 100644
--- 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
index 176c6b1..edbe081 100644
--- 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
index 7c6778c..729ce5e 100644
--- 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
index 8ec6a0d..7657806 100644
--- 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 {