From 4f2a12f330aec495641d21347de60c67ad2b5a88 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sat, 23 Jul 2022 14:48:06 -0600 Subject: [PATCH] Fix missing comments on indirectly created var-fns Resolves #2008 --- CHANGELOG.md | 1 + package.json | 3 ++- src/lib/converter/comments/discovery.ts | 11 +++++++++-- src/lib/converter/plugins/CommentPlugin.ts | 18 +++++++++++++++--- src/test/converter/function/specs.json | 16 ++++++++++++++++ src/test/converter2/issues/gh2008.ts | 4 ++++ src/test/converter2/validation/interface.ts | 5 +++++ src/test/issueTests.ts | 5 +++++ src/test/validation.test.ts | 11 +++++++++++ 9 files changed, 68 insertions(+), 6 deletions(-) create mode 100644 src/test/converter2/issues/gh2008.ts create mode 100644 src/test/converter2/validation/interface.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index f5e1c6ef3..0e3a0643f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ### Bug Fixes +- Fixed missing comments on callable variable-functions constructed indirectly, #2008. - Fixed multiple reflections mapping to the same file name on case insensitive file systems, #2012. ## v0.23.8 (2022-07-17) diff --git a/package.json b/package.json index 8985fdea1..fad69552a 100644 --- a/package.json +++ b/package.json @@ -66,7 +66,8 @@ "/tsdoc.json" ], "scripts": { - "test": "c8 mocha -r ts-node/register --config .config/mocha.fast.json", + "test": "mocha -r ts-node/register --config .config/mocha.fast.json", + "test:cov": "c8 mocha -r ts-node/register --config .config/mocha.fast.json", "build:c2": "node bin/typedoc --tsconfig src/test/converter2/tsconfig.json", "test:full": "c8 mocha -r ts-node/register --config .config/mocha.full.json", "test:visual": "node ./dist/test/capture-screenshots.js && reg-suit -c .config/regconfig.json compare", diff --git a/src/lib/converter/comments/discovery.ts b/src/lib/converter/comments/discovery.ts index 9e443848c..373ff5ad5 100644 --- a/src/lib/converter/comments/discovery.ts +++ b/src/lib/converter/comments/discovery.ts @@ -37,6 +37,9 @@ const wantedKinds: Record = { [ReflectionKind.Function]: [ ts.SyntaxKind.FunctionDeclaration, ts.SyntaxKind.BindingElement, + ts.SyntaxKind.VariableDeclaration, + ts.SyntaxKind.ExportAssignment, + ts.SyntaxKind.PropertyAccessExpression, ], [ReflectionKind.Class]: [ ts.SyntaxKind.ClassDeclaration, @@ -106,8 +109,12 @@ export function discoverComment( // See the gh1770 test for an example. if ( kind & ReflectionKind.ContainsCallSignatures && - !(node as ts.FunctionDeclaration).body && - node.kind !== ts.SyntaxKind.BindingElement + [ + ts.SyntaxKind.FunctionDeclaration, + ts.SyntaxKind.MethodDeclaration, + ts.SyntaxKind.Constructor, + ].includes(node.kind) && + !(node as ts.FunctionDeclaration).body ) { continue; } diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts index 71a6b363f..d4c162532 100644 --- a/src/lib/converter/plugins/CommentPlugin.ts +++ b/src/lib/converter/plugins/CommentPlugin.ts @@ -439,11 +439,23 @@ export class CommentPlugin extends ConverterComponent { return false; } - return ( + const isHidden = comment.hasModifier("@hidden") || comment.hasModifier("@ignore") || - (comment.hasModifier("@internal") && this.excludeInternal) - ); + (comment.hasModifier("@internal") && this.excludeInternal); + + if ( + isHidden && + reflection.kindOf(ReflectionKind.ContainsCallSignatures) + ) { + return (reflection as DeclarationReflection) + .getNonIndexSignatures() + .every((sig) => { + return !sig.comment || this.isHidden(sig); + }); + } + + return isHidden; } } diff --git a/src/test/converter/function/specs.json b/src/test/converter/function/specs.json index eea266563..12daa8fe2 100644 --- a/src/test/converter/function/specs.json +++ b/src/test/converter/function/specs.json @@ -449,6 +449,14 @@ "kind": 4096, "kindString": "Call signature", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Returns true if fn returns true for every item in the iterator\n\nReturns true if the iterator is empty" + } + ] + }, "typeParameter": [ { "id": 101, @@ -543,6 +551,14 @@ "kind": 4096, "kindString": "Call signature", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Returns true if fn returns true for every item in the iterator\n\nReturns true if the iterator is empty" + } + ] + }, "typeParameter": [ { "id": 108, diff --git a/src/test/converter2/issues/gh2008.ts b/src/test/converter2/issues/gh2008.ts new file mode 100644 index 000000000..61c323ae1 --- /dev/null +++ b/src/test/converter2/issues/gh2008.ts @@ -0,0 +1,4 @@ +const makeFn = () => () => {}; + +/** Docs */ +export const myFn = makeFn(); diff --git a/src/test/converter2/validation/interface.ts b/src/test/converter2/validation/interface.ts new file mode 100644 index 000000000..a057be41c --- /dev/null +++ b/src/test/converter2/validation/interface.ts @@ -0,0 +1,5 @@ +export interface Foo { + /** a */ + method(): void; + method(a: string): string; +} diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts index 5adc301fc..3198ab47b 100644 --- a/src/test/issueTests.ts +++ b/src/test/issueTests.ts @@ -666,6 +666,11 @@ export const issueTests: { equal(b.signatures![0].sources?.[0].character, 0); }, + gh2008(project) { + const fn = query(project, "myFn").signatures![0]; + equal(Comment.combineDisplayParts(fn.comment?.summary), "Docs"); + }, + gh2012(project) { project.hasOwnDocument = true; const model = query(project, "model"); diff --git a/src/test/validation.test.ts b/src/test/validation.test.ts index eba3abdf8..09c8a9d94 100644 --- a/src/test/validation.test.ts +++ b/src/test/validation.test.ts @@ -195,4 +195,15 @@ describe("validateDocumentation", () => { ); logger.expectNoOtherMessages(); }); + + it("Should correctly handle interfaces", () => { + const project = convertValidationFile("interface.ts"); + const logger = new TestLogger(); + validateDocumentation(project, logger, ["Method"]); + + logger.expectMessage( + "warn: Foo.method does not have any documentation." + ); + logger.expectNoOtherMessages(); + }); });