fix: Fix missing descriptions for function params (#357)

typedoc2md · Dec 2, 2022 · 817a11c · 817a11c
1 parent 70d9630
commit 817a11c
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 8 deletions.
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/parameter-table.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/parameter-table.ts
@@ -1,5 +1,5 @@
 import * as Handlebars from 'handlebars';
-import { ParameterReflection, ReflectionKind } from 'typedoc';
+import { ParameterReflection, ReflectionKind, ReflectionType } from 'typedoc';
 import { stripLineBreaks } from '../../utils';
 import { getReflectionType } from './type';
 
@@ -63,9 +63,8 @@ function table(parameters: any) {
     const optional = parameter.flags.isOptional ? '?' : '';
 
     const isDestructuredParam = parameter.name == '__namedParameters';
-    const isDestructuredParamProp = parameter.name.startsWith(
-      '__namedParameters.',
-    );
+    const isDestructuredParamProp =
+      parameter.name.startsWith('__namedParameters.');
 
     if (isDestructuredParam) {
       row.push(`\`${rest}«destructured»\``);
@@ -85,11 +84,13 @@ function table(parameters: any) {
       row.push(getDefaultValue(parameter));
     }
     if (hasComments) {
-      if (parameter.comment) {
+      const comments = getComments(parameter);
+      if (comments) {
         row.push(
-          stripLineBreaks(
-            Handlebars.helpers.comments(parameter.comment),
-          ).replace(/\|/g, '\\|'),
+          stripLineBreaks(Handlebars.helpers.comments(comments)).replace(
+            /\|/g,
+            '\\|',
+          ),
         );
       } else {
         row.push('-');
@@ -120,3 +121,15 @@ function hasDefaultValues(parameters: ParameterReflection[]) {
 
   return !defaultValues.every((value) => !value);
 }
+
+function getComments(parameter: any) {
+  if (parameter.type instanceof ReflectionType) {
+    if (
+      parameter.type?.declaration?.signatures &&
+      parameter.type?.declaration?.signatures[0]?.comment
+    ) {
+      return parameter.type?.declaration?.signatures[0]?.comment;
+    }
+  }
+  return parameter.comment;
+}
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/signatures.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/signatures.spec.ts.snap
@@ -113,6 +113,27 @@ Some nested params.
 "
 `;
 
+exports[`Signatures: should compile function with object params' 1`] = `
+"▸ **functionWithObjectParams**(\`topLevelCallback\`, \`params\`): \`void\`
+
+My Function.
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| \`topLevelCallback\` | () => \`void\` | A top-level callback. |
+| \`params\` | \`Object\` | Params object. |
+| \`params.callback1\` | () => \`void\` | A callback inside an object. |
+| \`params.callback2\` | () => \`void\` | A callback inside an object. |
+| \`params.testParam\` | \`number\` | Some number. |
+
+##### Returns
+
+\`void\`
+"
+`;
+
 exports[`Signatures: should compile function with reference type' 1`] = `
 "▸ **functionWithReferenceType**(\`descriptor\`): \`boolean\`
 

diff --git a/packages/typedoc-plugin-markdown/test/specs/signatures.spec.ts b/packages/typedoc-plugin-markdown/test/specs/signatures.spec.ts
@@ -189,4 +189,14 @@ describe(`Signatures:`, () => {
       ),
     ).toMatchSnapshot();
   });
+
+  test(`should compile function with object params'`, () => {
+    expect(
+      global.compileTemplate(
+        partial,
+        (project.getChildByName('functionWithObjectParams') as any)
+          .signatures[0] as SignatureReflection,
+      ),
+    ).toMatchSnapshot();
+  });
 });
diff --git a/stub-project/src/signatures.ts b/stub-project/src/signatures.ts
@@ -232,3 +232,20 @@ export const promiseReturningAnObject = (): Promise<{
     resolve({ id: 'id', data: 'data' });
   });
 };
+
+/**
+ * My Function.
+ * @param topLevelCallback A top-level callback.
+ * @param params Params object.
+ * @param params.callback1 A callback inside an object.
+ * @param params.testParam Some number.
+ * @param params.callback2 A callback inside an object.
+ */
+export function functionWithObjectParams(
+  topLevelCallback: () => void,
+  params: {
+    callback1: () => void;
+    testParam: number;
+    callback2: () => void;
+  },
+) {}