fix(compiler): fix transforming method parameters into docs (#5166)

fixes #4394
STENCIL-846

Author: christian-bromann

src/compiler/docs/generate-doc-data.ts

@@ -268,22 +268,25 @@ const parseTypeIntoValues = (type: string): d.JsonDocsValue[] => {
 const getDocsMethods = (methods: d.ComponentCompilerMethod[]): d.JsonDocsMethod[] => {
   return sortBy(methods, (member) => member.name)
     .filter((member) => !member.internal)
-    .map((member) => ({
-      name: member.name,
-      returns: {
-        type: member.complexType.return,
-        docs: member.docs.tags
-          .filter((t) => t.name === 'return' || t.name === 'returns')
-          .map((t) => t.text)
-          .join('\n'),
-      },
-      complexType: member.complexType,
-      signature: `${member.name}${member.complexType.signature}`,
-      parameters: [], // TODO
-      docs: member.docs.text,
-      docsTags: member.docs.tags,
-      deprecation: getDocsDeprecationText(member.docs.tags),
-    }));
+    .map(
+      (member) =>
+        <d.JsonDocsMethod>{
+          name: member.name,
+          returns: {
+            type: member.complexType.return,
+            docs: member.docs.tags
+              .filter((t) => t.name === 'return' || t.name === 'returns')
+              .map((t) => t.text)
+              .join('\n'),
+          },
+          complexType: member.complexType,
+          signature: `${member.name}${member.complexType.signature}`,
+          parameters: member.complexType.parameters,
+          docs: member.docs.text,
+          docsTags: member.docs.tags,
+          deprecation: getDocsDeprecationText(member.docs.tags),
+        },
+    );
 };
 
 const getDocsEvents = (events: d.ComponentCompilerEvent[]): d.JsonDocsEvent[] => {

src/compiler/transformers/decorators-to-static/method-decorator.ts

@@ -11,7 +11,6 @@ import {
   mapJSDocTagInfo,
   retrieveTsDecorators,
   retrieveTsModifiers,
-  serializeSymbol,
   typeToString,
   validateReferences,
 } from '../transform-utils';
@@ -96,7 +95,11 @@ const parseMethodDecorator = (
   const methodMeta: d.ComponentCompilerStaticMethod = {
     complexType: {
       signature: signatureString,
-      parameters: signature.parameters.map((symbol) => serializeSymbol(typeChecker, symbol)),
+      parameters: signature.parameters.map((symbol) => ({
+        name: symbol.getName(),
+        type: typeToString(typeChecker, typeChecker.getTypeOfSymbolAtLocation(symbol, method)),
+        docs: ts.displayPartsToString(symbol.getDocumentationComment(typeChecker)),
+      })),
       references: {
         ...getAttributeTypeInfo(returnTypeNode, tsSourceFile, typeChecker, program),
         ...getAttributeTypeInfo(method, tsSourceFile, typeChecker, program),

src/compiler/transformers/test/parse-comments.spec.ts

@@ -61,8 +61,9 @@ describe('parse comments', () => {
       complexType: {
         parameters: [
           {
-            tags: [],
-            text: '',
+            name: 'prop',
+            type: 'string',
+            docs: '',
           },
         ],
         return: 'unknown',

src/compiler/transformers/test/parse-methods.spec.ts

@@ -5,39 +5,52 @@ describe('parse methods', () => {
     const t = transpileModule(`
       @Component({tag: 'cmp-a'})
       export class CmpA {
+        /**
+         * @param foo bar
+         * @param bar foo
+         */
         @Method()
-        someMethod() {
+        someMethod(foo: string, bar: number) {
 
         }
       }
     `);
 
-    expect(getStaticGetter(t.outputText, 'methods')).toEqual({
-      someMethod: {
-        complexType: {
-          parameters: [],
-          return: 'void',
-          references: {},
-          signature: '() => void',
-        },
-        docs: {
-          text: '',
-          tags: [],
-        },
-      },
-    });
-
-    expect(t.method).toEqual({
+    const someMethod = {
       complexType: {
-        parameters: [],
+        parameters: [
+          {
+            name: 'foo',
+            type: 'string',
+            docs: 'bar',
+          },
+          {
+            name: 'bar',
+            type: 'number',
+            docs: 'foo',
+          },
+        ],
         return: 'void',
         references: {},
-        signature: '() => void',
+        signature: '(foo: string, bar: number) => void',
       },
       docs: {
-        tags: [],
         text: '',
+        tags: [
+          {
+            name: 'param',
+            text: 'foo bar',
+          },
+          {
+            name: 'param',
+            text: 'bar foo',
+          },
+        ],
       },
+    };
+    expect(getStaticGetter(t.outputText, 'methods')).toEqual({ someMethod });
+    expect(t.method).toEqual({
+      ...someMethod,
       internal: false,
       name: 'someMethod',
     });

src/compiler/types/tests/ComponentCompilerMethod.stub.ts

@@ -14,7 +14,7 @@ export const stubComponentCompilerMethod = (
     name: 'myMethod',
     internal: false,
     complexType: {
-      parameters: [{ tags: [], text: '' }],
+      parameters: [{ name: 'name', type: 'Foo', docs: '' }],
       references: { Foo: { location: 'import', path: './resources', id: 'placeholder' } },
       return: 'Promise<void>',
       signature: '(name: Foo) => Promise<void>',

src/compiler/types/tests/generate-method-types.spec.ts

@@ -97,7 +97,7 @@ describe('generate-method-types', () => {
         name: 'myOtherMethod',
         internal: true,
         complexType: {
-          parameters: [{ tags: [], text: '' }],
+          parameters: [{ name: 'age', type: 'Bar', docs: '' }],
           references: { Bar: { location: 'local', id: 'placeholder_id', path: './other-resources' } },
           return: 'Promise<boolean>',
           signature: '(age: Bar) => Promise<boolean>',

src/declarations/stencil-private.ts

@@ -28,6 +28,7 @@ import type {
   TaskCommand,
   ValidatedConfig,
 } from './stencil-public-compiler';
+import type { JsonDocMethodParameter } from './stencil-public-docs';
 import type { ComponentInterface, ListenTargetOptions, VNode } from './stencil-public-runtime';
 
 export interface SourceMap {
@@ -799,7 +800,7 @@ export interface ComponentCompilerStaticMethod {
 
 export interface ComponentCompilerMethodComplexType {
   signature: string;
-  parameters: CompilerJsDoc[];
+  parameters: JsonDocMethodParameter[];
   references: ComponentCompilerTypeReferences;
   return: string;
 }

test/docs-json/docs.d.ts

@@ -60,30 +60,10 @@ interface ComponentCompilerEventComplexType {
 }
 interface ComponentCompilerMethodComplexType {
   signature: string;
-  parameters: CompilerJsDoc[];
+  parameters: JsonDocMethodParameter[];
   references: ComponentCompilerTypeReferences;
   return: string;
 }
-interface CompilerJsDoc {
-  /**
-   * The text associated with the JSDoc
-   */
-  text: string;
-  /**
-   * Tags included in the JSDoc
-   */
-  tags: CompilerJsDocTagInfo[];
-}
-interface CompilerJsDocTagInfo {
-  /**
-   * The name of the tag - e.g. `@deprecated`
-   */
-  name: string;
-  /**
-   * Additional text that is associated with the tag - e.g. `@deprecated use v2 of this API`
-   */
-  text?: string;
-}
 /**
  * The Type Library holds information about the types which are used in a
  * Stencil project. During compilation, Stencil gathers information about the

test/docs-json/docs.json

@@ -19,8 +19,9 @@
             "signature": "<T>(arg: T) => Promise<ImportedInterface<T>>",
             "parameters": [
               {
-                "tags": [],
-                "text": ""
+                "name": "arg",
+                "type": "T",
+                "docs": ""
               }
             ],
             "references": {
@@ -41,7 +42,13 @@
             "return": "Promise<ImportedInterface<T>>"
           },
           "signature": "onDidDismiss<T>(arg: T) => Promise<ImportedInterface<T>>",
-          "parameters": [],
+          "parameters": [
+            {
+              "name": "arg",
+              "type": "T",
+              "docs": ""
+            }
+          ],
           "docs": "A comment, which should be included, I should think!",
           "docsTags": []
         }

test/end-to-end/src/components.d.ts

@@ -33,8 +33,21 @@ export namespace Components {
     interface EnvData {
     }
     interface EventCmp {
+        /**
+          * this is some method that fires an event with options
+          * @returns
+         */
         "methodThatFiresEventWithOptions": () => Promise<void>;
+        /**
+          * this is some method that fires a document event
+          * @returns
+         */
         "methodThatFiresMyDocumentEvent": () => Promise<void>;
+        /**
+          * this is some method that fires a window event
+          * @param value some value
+          * @returns
+         */
         "methodThatFiresMyWindowEvent": (value: number) => Promise<void>;
     }
     interface ImportAssets {
@@ -43,7 +56,17 @@ export namespace Components {
         "opened": boolean;
     }
     interface MethodCmp {
+        /**
+          * this is some method
+          * @returns some number
+         */
         "someMethod": () => Promise<number>;
+        /**
+          * this is some method with args
+          * @param unit some unit
+          * @param value some value
+          * @returns some string
+         */
         "someMethodWithArgs": (unit: string, value: number) => Promise<string>;
         "someProp": number;
     }

test/end-to-end/src/event-cmp/event-cmp.tsx

@@ -15,16 +15,29 @@ export class EventCmp {
 
   @Event() myWindowEvent: EventEmitter<number>;
 
+  /**
+   * this is some method that fires a window event
+   * @param value some value
+   * @returns {void}
+   */
   @Method()
   async methodThatFiresMyWindowEvent(value: number) {
     this.myWindowEvent.emit(value);
   }
 
+  /**
+   * this is some method that fires a document event
+   * @returns {void}
+   */
   @Method()
   async methodThatFiresMyDocumentEvent() {
     this.myDocumentEvent.emit();
   }
 
+  /**
+   * this is some method that fires an event with options
+   * @returns {void}
+   */
   @Method()
   async methodThatFiresEventWithOptions() {
     this.myEventWithOptions.emit({ mph: 88 });

test/end-to-end/src/event-cmp/readme.md

@@ -18,7 +18,7 @@
 
 ### `methodThatFiresEventWithOptions() => Promise<void>`
 
-
+this is some method that fires an event with options
 
 #### Returns
 
@@ -28,7 +28,7 @@ Type: `Promise<void>`
 
 ### `methodThatFiresMyDocumentEvent() => Promise<void>`
 
-
+this is some method that fires a document event
 
 #### Returns
 
@@ -38,7 +38,13 @@ Type: `Promise<void>`
 
 ### `methodThatFiresMyWindowEvent(value: number) => Promise<void>`
 
+this is some method that fires a window event
+
+#### Parameters
 
+| Name    | Type     | Description |
+| ------- | -------- | ----------- |
+| `value` | `number` | some value  |
 
 #### Returns
 

test/end-to-end/src/method-cmp/method-cmp.tsx

@@ -6,11 +6,21 @@ import { Component, Method, Prop } from '@stencil/core';
 export class MethodCmp {
   @Prop() someProp = 0;
 
+  /**
+   * this is some method
+   * @returns {number} some number
+   */
   @Method()
   async someMethod() {
     return this.someProp;
   }
 
+  /**
+   * this is some method with args
+   * @param unit some unit
+   * @param value some value
+   * @returns {string} some string
+   */
   @Method()
   async someMethodWithArgs(unit: string, value: number) {
     return `${value} ${unit}`;

test/end-to-end/src/method-cmp/readme.md

@@ -16,23 +16,30 @@
 
 ### `someMethod() => Promise<number>`
 
-
+this is some method
 
 #### Returns
 
 Type: `Promise<number>`
 
-
+some number
 
 ### `someMethodWithArgs(unit: string, value: number) => Promise<string>`
 
+this is some method with args
 
+#### Parameters
+
+| Name    | Type     | Description |
+| ------- | -------- | ----------- |
+| `unit`  | `string` | some unit   |
+| `value` | `number` | some value  |
 
 #### Returns
 
 Type: `Promise<string>`
 
-
+some string
 
 
 ----------------------------------------------