fix(core): expose "@return" block tags on declarations (#694)

typedoc2md · Oct 1, 2024 · 300db20 · 300db20
1 parent 63aae5b
commit 300db20
Show file tree

Hide file tree

Showing 10 changed files with 70 additions and 1 deletion.
diff --git a/.changeset/orange-horses-beg.md b/.changeset/orange-horses-beg.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Expose "@return" block tags on declarations (#694)
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts
@@ -10,13 +10,15 @@ export function comment(
     headingLevel?: number;
     showSummary?: boolean;
     showTags?: boolean;
+    showReturns?: boolean;
     isTableColumn?: boolean;
   } = {},
 ) {
   const opts = {
     headingLevel: undefined,
     showSummary: true,
     showTags: true,
+    showReturns: false,
     isTableColumn: false,
     ...options,
   };
@@ -83,7 +85,7 @@ export function comment(
       [],
     );
 
-    const filteredBlockTags = ['@returns'];
+    const filteredBlockTags = opts.showReturns ? [] : ['@returns'];
 
     const tags = blockTags
       .filter((tag) => !filteredBlockTags.includes(tag.tag))

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
@@ -163,6 +163,7 @@ export function declaration(
         headingLevel: opts.headingLevel,
         showSummary: false,
         showTags: true,
+        showReturns: true,
       }),
     );
   }

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts
@@ -74,6 +74,7 @@ export const resourcePartials = (context: MarkdownThemeContext) => {
         headingLevel?: number | undefined;
         showSummary?: boolean | undefined;
         showTags?: boolean | undefined;
+        showReturns?: boolean | undefined;
         isTableColumn?: boolean | undefined;
       } = {},
     ) => partials.comment.apply(context, [model, options]) as string,

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/types.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/types.ts
@@ -207,3 +207,11 @@ export type __TypeDeclarationWithSpecialCharacters_<T, U> = {
   '|prop|with|pipes|': '|prop|with|pipes|';
   '`prop`with`backticks`': '`prop`with`backticks`';
 };
+
+/**
+ * Comments for TypeWithReturns
+ *
+ * @returns
+ * - return comments.
+ */
+export type TypeWithReturns = string;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap
@@ -4486,6 +4486,11 @@ exports[`Navigation should gets Navigation Json for single entry point: (Output
         "kind": 2097152,
         "path": "type-aliases/TypeWithExternalSymbolLinkMapping.md"
       },
+      {
+        "title": "TypeWithReturns",
+        "kind": 2097152,
+        "path": "type-aliases/TypeWithReturns.md"
+      },
       {
         "title": "TypeWithTypeParams",
         "kind": 2097152,

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.index.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.index.spec.ts.snap
@@ -87,6 +87,7 @@ Module commments
 | [StringLiteralType](type-aliases/StringLiteralType.md) | Comments for StringLiteralType |
 | [TupleType](type-aliases/TupleType.md) | Comments for TupleType |
 | [TypeWithExternalSymbolLinkMapping](type-aliases/TypeWithExternalSymbolLinkMapping.md) | Comments for TypeWithExternalSymbolLinkMapping |
+| [TypeWithReturns](type-aliases/TypeWithReturns.md) | Comments for TypeWithReturns |
 | [TypeWithTypeParams](type-aliases/TypeWithTypeParams.md) | Comments for TypeWithTypeParams |
 | [UnionType](type-aliases/UnionType.md) | Comments for UnionType |
 | [UnionTypeWithTemplateStrings](type-aliases/UnionTypeWithTemplateStrings.md) | Union with template strings |

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.type-alias.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.type-alias.spec.ts.snap
@@ -625,6 +625,42 @@ Comments for TypeWithTypeParams
 "
 `;
 
+exports[`Type Alias Reflection should compile type with returns: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Type Alias: TypeWithReturns
+
+> **TypeWithReturns**: \`string\`
+
+Comments for TypeWithReturns
+
+## Returns
+
+- return comments.
+
+## Source
+
+[types.ts:1](http://source-url)
+"
+`;
+
+exports[`Type Alias Reflection should compile type with returns: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Type Alias: TypeWithReturns
+
+\`\`\`ts
+type TypeWithReturns: string;
+\`\`\`
+
+Comments for TypeWithReturns
+
+## Returns
+
+- return comments.
+
+## Source
+
+[types.ts:1](http://source-url)
+"
+`;
+
 exports[`Type Alias Reflection should compile union type with template strings: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Type Alias: UnionTypeWithTemplateStrings
 

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -842,6 +842,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb
   "type-aliases/TupleType.md",
   "type-aliases/TypeDeclarationWithSpecialCharacters.md",
   "type-aliases/TypeWithExternalSymbolLinkMapping.md",
+  "type-aliases/TypeWithReturns.md",
   "type-aliases/TypeWithTypeParams.md",
   "type-aliases/UnionType.md",
   "type-aliases/UnionTypeWithTemplateStrings.md",
@@ -923,6 +924,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb
   "type-aliases/TupleType.md",
   "type-aliases/TypeDeclarationWithSpecialCharacters.md",
   "type-aliases/TypeWithExternalSymbolLinkMapping.md",
+  "type-aliases/TypeWithReturns.md",
   "type-aliases/TypeWithTypeParams.md",
   "type-aliases/UnionType.md",
   "type-aliases/UnionTypeWithTemplateStrings.md",

diff --git a/packages/typedoc-plugin-markdown/test/specs/reflection.type-alias.spec.ts b/packages/typedoc-plugin-markdown/test/specs/reflection.type-alias.spec.ts
@@ -112,4 +112,12 @@ describe(`Type Alias Reflection`, () => {
       'type-aliases/UnionTypeWithTemplateStrings.md',
     );
   });
+
+  test(`should compile type with returns`, () => {
+    expectFileToEqual(
+      'reflections',
+      'members',
+      'type-aliases/TypeWithReturns.md',
+    );
+  });
 });