fix(core): fix missing index descriptions for signatures (#618)

typedoc2md · Jul 11, 2024 · 3e685ab · 3e685ab
1 parent 579705a
commit 3e685ab
Show file tree

Hide file tree

Showing 9 changed files with 50 additions and 28 deletions.
diff --git a/.changeset/pretty-impalas-approve.md b/.changeset/pretty-impalas-approve.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Fix missing index descriptions for signatures (#618)
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts
@@ -1,7 +1,8 @@
 export * from './get-angle-bracket';
+export * from './get-comment-for-reflection';
 export * from './get-comment-parts';
 export * from './get-declaration-type';
-export * from './get-description-for-reflection';
+export * from './get-description-for-comment';
 export * from './get-flattened-declarations';
 export * from './get-group-index-list';
 export * from './get-group-index-table';

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-for-reflection.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-for-reflection.ts
@@ -0,0 +1,5 @@
+import { DeclarationReflection } from 'typedoc';
+
+export function getCommentForReflection(model: DeclarationReflection) {
+  return model.signatures?.length ? model.signatures[0].comment : model.comment;
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-comment.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-comment.ts
@@ -0,0 +1,15 @@
+import { MarkdownThemeContext } from 'theme';
+import { Comment } from 'typedoc';
+
+export function getDescriptionForComment(
+  this: MarkdownThemeContext,
+  comment: Comment,
+) {
+  if (comment?.summary?.length) {
+    return this.helpers
+      .getCommentParts(comment.summary)
+      ?.split(/(\r?\n){2}/)[0]
+      .replace(/\r?\n/g, ' ');
+  }
+  return null;
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-group-index-table.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-group-index-table.ts
@@ -36,14 +36,17 @@ export function getGroupIndexTable(
       if (child instanceof DocumentReflection) {
         return child.frontmatter.description as string;
       }
-      if (!child.comment) {
+
+      const comment = this.helpers.getCommentForReflection(child);
+
+      if (!comment) {
         return '';
       }
       return isHtmlTable
-        ? this.partials.comment(child.comment, {
+        ? this.partials.comment(comment, {
             isTableColumn: true,
           })
-        : this.helpers.getDescriptionForReflection(child);
+        : this.helpers.getDescriptionForComment(comment);
     };
 
     row.push(description() || '-');

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts
@@ -268,14 +268,18 @@ export const resourceHelpers = (context: MarkdownThemeContext) => {
   return {
     getAngleBracket: (bracket: '<' | '>') =>
       helpers.getAngleBracket.apply(context, [bracket]) as string,
+    getCommentForReflection: (model: DeclarationReflection) =>
+      helpers.getCommentForReflection.apply(context, [model]) as
+        | Comment
+        | undefined,
     getCommentParts: (model: CommentDisplayPart[]) =>
       helpers.getCommentParts.apply(context, [model]) as string,
     getDeclarationType: (model: DeclarationReflection) =>
       helpers.getDeclarationType.apply(context, [model]) as
         | SomeType
         | undefined,
-    getDescriptionForReflection: (model: DeclarationReflection) =>
-      helpers.getDescriptionForReflection.apply(context, [model]) as
+    getDescriptionForComment: (comment: Comment) =>
+      helpers.getDescriptionForComment.apply(context, [comment]) as
         | string
         | null,
     getFlattenedDeclarations: (

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts
@@ -49,8 +49,13 @@ export type TypeA = string;
  */
 export type TypeB = (str: string, offset?: number) => any;
 /**
- * functionA function.
+ * Create a function.
+ *
+ * More summary.
+ *
+ * @param rules - rules.
+ * @param options - options.
  */
-export function functionA() {}
+export function functionA(rules: any, options?: any) {}
 export const variableA = '';
 export const variableB = '';
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap
@@ -52,7 +52,7 @@ A basic module
 
 | Function | Description |
 | :------ | :------ |
-| [functionA](functions/functionA.md) | - |
+| [functionA](functions/functionA.md) | Create a function. |
 "
 `;
 
@@ -227,7 +227,9 @@ TypeB function.
 </td>
 <td>
 
-&hyphen;
+Create a function.
+
+More summary.
 
 </td>
 </tr>