From ba8956c99e814df441eeec2283b304ac3358c670 Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Mon, 26 Aug 2024 00:03:56 +0100 Subject: [PATCH] fix(core): fix missing index descriptions for some signatures (#670) --- .changeset/metal-shirts-invite.md | 5 +++++ .../src/theme/context/helpers/_index.ts | 1 - .../theme/context/helpers/get-comment-for-reflection.ts | 7 ------- .../src/theme/context/helpers/get-group-index-table.ts | 2 +- .../src/theme/context/resources.ts | 4 ---- .../test/fixtures/src/reflections/functions.ts | 9 +++++++++ .../test/specs/__snapshots__/navigation.spec.ts.snap | 5 +++++ .../specs/__snapshots__/reflection.index.spec.ts.snap | 3 ++- .../test/specs/__snapshots__/urls.spec.ts.snap | 2 ++ 9 files changed, 24 insertions(+), 14 deletions(-) create mode 100644 .changeset/metal-shirts-invite.md delete mode 100644 packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-for-reflection.ts diff --git a/.changeset/metal-shirts-invite.md b/.changeset/metal-shirts-invite.md new file mode 100644 index 000000000..01f92902d --- /dev/null +++ b/.changeset/metal-shirts-invite.md @@ -0,0 +1,5 @@ +--- +'typedoc-plugin-markdown': patch +--- + +- Fix missing index descriptions for some signatures (#670) diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts index dc28d042a..93a2aad7a 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts @@ -1,5 +1,4 @@ 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-comment'; 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 deleted file mode 100644 index 645a3e2db..000000000 --- a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-for-reflection.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { DeclarationReflection } from 'typedoc'; - -export function getCommentForReflection(model: DeclarationReflection) { - return model.signatures?.length - ? model.signatures[0].comment || model.comment - : model.comment; -} 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 index 7bb99bc17..6ba36be5f 100644 --- 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 @@ -37,7 +37,7 @@ export function getGroupIndexTable( return child.frontmatter.description as string; } - const comment = this.helpers.getCommentForReflection(child); + const comment = child.comment || child.signatures?.[0]?.comment; if (!comment) { return ''; diff --git a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts index 7ca09eec8..7b0daacf5 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts @@ -268,10 +268,6 @@ 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) => diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts index c72327538..07abd50e5 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts @@ -13,6 +13,15 @@ export const basicFunction = (someParam: number) => { return 0; }; +/** + * This is a function that is assigned to a variable. + * + * @returns This is a return value + */ +export const basicFunctionWithReturns = () => { + return 0; +}; + /** * This is a function with a parameter that has a default value. * 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 528ddd8a5..0aed462d5 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 @@ -4408,6 +4408,11 @@ exports[`Navigation should gets Navigation Json for single entry point: (Output "kind": 64, "path": "functions/basicFunction.md" }, + { + "title": "basicFunctionWithReturns", + "kind": 64, + "path": "functions/basicFunctionWithReturns.md" + }, { "title": "functionReturningAFunction", "kind": 64, 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 1f093416f..ce919a6af 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 @@ -108,6 +108,7 @@ Module commments | Function | Description | | :------ | :------ | | [basicFunction](functions/basicFunction.md) | This is a function that is assigned to a variable. | +| [basicFunctionWithReturns](functions/basicFunctionWithReturns.md) | This is a function that is assigned to a variable. | | [functionReturningAFunction](functions/functionReturningAFunction.md) | Comments for function | | [functionReturningAPromise](functions/functionReturningAPromise.md) | Comments for function | | [functionReturningAString](functions/functionReturningAString.md) | Comments for function | @@ -115,7 +116,7 @@ Module commments | [functionReturningAnObject](functions/functionReturningAnObject.md) | Comments for function | | [functionWithComplexParams](functions/functionWithComplexParams.md) | Function with function parmas | | [functionWithDefaultParameters](functions/functionWithDefaultParameters.md) | This is a function with a parameter that has a default value. | -| [functionWithMultipleSignatures](functions/functionWithMultipleSignatures.md) | This is the first signature of a function with multiple signatures. | +| [functionWithMultipleSignatures](functions/functionWithMultipleSignatures.md) | Main function comment. | | [functionWithNamedParams](functions/functionWithNamedParams.md) | - | | [functionWithNestedParameters](functions/functionWithNestedParameters.md) | Some nested params. | | [functionWithOptionalParameters](functions/functionWithOptionalParameters.md) | This is a function with a parameters. | 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 e3ffee0e4..ab60b8d88 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 @@ -800,6 +800,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb "enumerations/BasicEnum.md", "enumerations/EnumWithValues.md", "functions/basicFunction.md", + "functions/basicFunctionWithReturns.md", "functions/functionReturningAFunction.md", "functions/functionReturningAPromise.md", "functions/functionReturningAString.md", @@ -881,6 +882,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb "enumerations/BasicEnum.md", "enumerations/EnumWithValues.md", "functions/basicFunction.md", + "functions/basicFunctionWithReturns.md", "functions/functionReturningAFunction.md", "functions/functionReturningAPromise.md", "functions/functionReturningAString.md",