diff --git a/.changeset/great-comics-notice.md b/.changeset/great-comics-notice.md new file mode 100644 index 000000000..a19d8eca6 --- /dev/null +++ b/.changeset/great-comics-notice.md @@ -0,0 +1,5 @@ +--- +'typedoc-plugin-markdown': patch +--- + +- Correctly resolve comment summary for const functions (#656) diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts index 4fec230d1..ed44f3612 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts @@ -22,7 +22,22 @@ export function signature( ); } - const modelComments = model.comment || model.parent?.comment; + let modelComments = model.comment || model.parent?.comment; + + if ( + modelComments && + model.parent?.comment?.summary && + !options.multipleSignatures + ) { + modelComments = Object.assign(modelComments, { + summary: model.parent.comment.summary, + }); + } + if (modelComments && model.parent?.comment?.blockTags) { + modelComments = Object.assign(modelComments, { + blockTags: model.parent.comment.blockTags, + }); + } if (modelComments) { md.push( diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts index 58a48baef..ce698747f 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts @@ -141,11 +141,37 @@ export function multipleExampleTags() { * ```ts * factorial(1) * ``` + * + * @returns Return comments */ export function singleExampleTag() { return true; } +/** + * constFunction comments + * + * @param text Some param + * + * @remarks Some remarks + */ +export const constFunction = (text: string) => { + return true; +}; + +/** + * constFunctionWithReturns comments + * + * @param text Some param + * + * @returns Return comments + * + * @remarks Some remarks + */ +export const constFunctionWithReturns = (text: string) => { + return true; +}; + export class BaseClassProperties { /** * @deprecated diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap index f6ca5f1ab..85b643095 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap @@ -119,6 +119,8 @@ Some

html

inside codeblock ## Functions +- [constFunction](functions/constFunction.md) +- [constFunctionWithReturns](functions/constFunctionWithReturns.md) - [functionWithBlockTags](functions/functionWithBlockTags.md) - [multipleExampleTags](functions/multipleExampleTags.md) - [parametersTable](functions/parametersTable.md) @@ -724,6 +726,60 @@ Other block tags " `; +exports[`Comments should handle const function with returns: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Function: constFunctionWithReturns() + +> **constFunctionWithReturns**(\`text\`): \`boolean\` + +constFunctionWithReturns comments + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| \`text\` | \`string\` | Some param | + +## Returns + +\`boolean\` + +## Remarks + +Some remarks + +## Source + +[index.ts:1](http://source-url) +" +`; + +exports[`Comments should handle const function: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Function: constFunction() + +> **constFunction**(\`text\`): \`boolean\` + +constFunction comments + +## Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| \`text\` | \`string\` | Some param | + +## Returns + +\`boolean\` + +## Remarks + +Some remarks + +## Source + +[index.ts:1](http://source-url) +" +`; + exports[`Comments should handle multiple example tags: (Output File Strategy "members") (Option Group "1") 1`] = ` "# Function: multipleExampleTags() @@ -759,25 +815,19 @@ factorial(1) `; exports[`Comments should handle single example tags: (Output File Strategy "members") (Option Group "1") 1`] = ` -"# Function: multipleExampleTags() +"# Function: singleExampleTag() -> **multipleExampleTags**(): \`boolean\` +> **singleExampleTag**(): \`boolean\` -Function with multiple example tags +Function with single example tag ## Returns \`boolean\` -## Examples +Return comments -\`\`\`ts -// If there are no code blocks, TypeDoc assumes the whole tag -// should be a code block. This is not valid TSDoc, but is recognized -// by VSCode and enables better JSDoc support. - -factorial(1) -\`\`\` +## Example If there is a code block, then both TypeDoc and VSCode will treat text outside of the code block as regular text. 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 000e9299c..c685231b2 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 @@ -965,6 +965,8 @@ exports[`Urls should gets Urls with media assets: outputFileStrategy: members 1` "classes/ClassPropertiesTable.md", "enumerations/CommentEnum.md", "enumerations/EnumMembersTable.md", + "functions/constFunction.md", + "functions/constFunctionWithReturns.md", "functions/functionWithBlockTags.md", "functions/multipleExampleTags.md", "functions/parametersTable.md", @@ -991,6 +993,8 @@ exports[`Urls should gets Urls with media assets: outputFileStrategy: members 2` "Class.ClassPropertiesTable.md", "Enumeration.CommentEnum.md", "Enumeration.EnumMembersTable.md", + "Function.constFunction.md", + "Function.constFunctionWithReturns.md", "Function.functionWithBlockTags.md", "Function.multipleExampleTags.md", "Function.parametersTable.md", diff --git a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts index 42612d64e..7d6157540 100644 --- a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts +++ b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts @@ -13,7 +13,7 @@ describe(`Comments`, () => { expectFileToEqual( 'comments', ['members'], - ['/functions/multipleExampleTags.md'], + ['/functions/singleExampleTag.md'], ); }); @@ -25,6 +25,18 @@ describe(`Comments`, () => { ); }); + test(`should handle const function`, () => { + expectFileToEqual('comments', ['members'], ['/functions/constFunction.md']); + }); + + test(`should handle const function with returns`, () => { + expectFileToEqual( + 'comments', + ['members'], + ['/functions/constFunctionWithReturns.md'], + ); + }); + test(`should get tables for properties`, () => { expectFileToEqual('comments', 'members', [ '/classes/ClassPropertiesTable.md',