From 300db20d9d72bc5ce61b5423c085cdab788c3646 Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Mon, 30 Sep 2024 21:25:26 +0100 Subject: [PATCH] fix(core): expose "@return" block tags on declarations (#694) --- .changeset/orange-horses-beg.md | 5 +++ .../context/partials/comments.comment.ts | 4 ++- .../context/partials/member.declaration.ts | 1 + .../src/theme/context/resources.ts | 1 + .../test/fixtures/src/reflections/types.ts | 8 +++++ .../__snapshots__/navigation.spec.ts.snap | 5 +++ .../reflection.index.spec.ts.snap | 1 + .../reflection.type-alias.spec.ts.snap | 36 +++++++++++++++++++ .../specs/__snapshots__/urls.spec.ts.snap | 2 ++ .../test/specs/reflection.type-alias.spec.ts | 8 +++++ 10 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 .changeset/orange-horses-beg.md diff --git a/.changeset/orange-horses-beg.md b/.changeset/orange-horses-beg.md new file mode 100644 index 000000000..13efbdaf6 --- /dev/null +++ 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 index d6eab1de7..35144d2d5 100644 --- 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,6 +10,7 @@ export function comment( headingLevel?: number; showSummary?: boolean; showTags?: boolean; + showReturns?: boolean; isTableColumn?: boolean; } = {}, ) { @@ -17,6 +18,7 @@ export function comment( 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 index 3bfa99eed..3f99a34ac 100644 --- 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 index 7b0daacf5..7b44ae4ab 100644 --- 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 index aacc94f7f..8e3b004f6 100644 --- 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_ = { '|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 index dd79f58c3..bc00c7f3b 100644 --- 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 index ce919a6af..5a048a43f 100644 --- 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 index 535654a1d..895af1af4 100644 --- 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 index ab60b8d88..5f4e7b0e3 100644 --- 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 index ea558089f..a967ab50f 100644 --- 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', + ); + }); });