From 9671e18654a5d906d3dd5035c68f0a93e13abb75 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sun, 23 Oct 2022 13:51:51 -0600 Subject: [PATCH] Fix comments for constructor properties Resolves #1261 --- CHANGELOG.md | 1 + src/lib/converter/comments/index.ts | 31 ++++++- .../class/specs-with-lump-categories.json | 80 +++++++++++++++++++ src/test/converter/class/specs.json | 80 +++++++++++++++++++ src/test/converter2/issues/gh1261.ts | 7 ++ src/test/issueTests.ts | 8 ++ 6 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 src/test/converter2/issues/gh1261.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 42cad1cb9..1d4aeb29d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ### Bug Fixes +- Constructor parameter-properties will now use the `@param` comment for the parameter if available, #1261. - Fixed display of object types containing methods, #1788. - Fixed conversion of intrinsic string mapping types when converting without a type node, #2079. diff --git a/src/lib/converter/comments/index.ts b/src/lib/converter/comments/index.ts index af54e4431..fe55d4a7f 100644 --- a/src/lib/converter/comments/index.ts +++ b/src/lib/converter/comments/index.ts @@ -115,12 +115,41 @@ export function getComment( ); } - return getCommentImpl( + const comment = getCommentImpl( discoverComment(symbol, kind, logger, commentStyle), config, logger, symbol.declarations?.some(ts.isSourceFile) || false ); + + if (!comment && kind === ReflectionKind.Property) { + return getConstructorParamPropertyComment( + symbol, + config, + logger, + commentStyle + ); + } + + return comment; +} + +function getConstructorParamPropertyComment( + symbol: ts.Symbol, + config: CommentParserConfig, + logger: Logger, + commentStyle: CommentStyle +): Comment | undefined { + const decl = symbol.declarations?.find(ts.isParameter); + if (!decl) return; + + const ctor = decl.parent; + const comment = getSignatureComment(ctor, config, logger, commentStyle); + + const paramTag = comment?.getIdentifiedTag(symbol.name, "@param"); + if (paramTag) { + return new Comment(paramTag.content); + } } export function getSignatureComment( diff --git a/src/test/converter/class/specs-with-lump-categories.json b/src/test/converter/class/specs-with-lump-categories.json index 303804daa..4f3c0b863 100644 --- a/src/test/converter/class/specs-with-lump-categories.json +++ b/src/test/converter/class/specs-with-lump-categories.json @@ -1573,6 +1573,14 @@ "flags": { "isPrivate": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Private string property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -1594,6 +1602,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Public number property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -1615,6 +1631,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Public implicit any property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -2265,6 +2289,14 @@ "flags": { "isReadonly": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Vector name" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2286,6 +2318,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "X component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2307,6 +2347,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Y component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2493,6 +2541,14 @@ "flags": { "isReadonly": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Vector name" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2519,6 +2575,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "X component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2545,6 +2609,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Y component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2571,6 +2643,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Z component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", diff --git a/src/test/converter/class/specs.json b/src/test/converter/class/specs.json index 2d5a6ebae..799355572 100644 --- a/src/test/converter/class/specs.json +++ b/src/test/converter/class/specs.json @@ -1569,6 +1569,14 @@ "flags": { "isPrivate": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Private string property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -1590,6 +1598,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Public number property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -1611,6 +1627,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Public implicit any property" + } + ] + }, "sources": [ { "fileName": "class.ts", @@ -2261,6 +2285,14 @@ "flags": { "isReadonly": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Vector name" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2282,6 +2314,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "X component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2303,6 +2343,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Y component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2489,6 +2537,14 @@ "flags": { "isReadonly": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Vector name" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2515,6 +2571,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "X component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2541,6 +2605,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Y component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", @@ -2567,6 +2639,14 @@ "flags": { "isPublic": true }, + "comment": { + "summary": [ + { + "kind": "text", + "text": "Z component of the Vector" + } + ] + }, "sources": [ { "fileName": "constructor-properties.ts", diff --git a/src/test/converter2/issues/gh1261.ts b/src/test/converter2/issues/gh1261.ts new file mode 100644 index 000000000..c4ca54c5b --- /dev/null +++ b/src/test/converter2/issues/gh1261.ts @@ -0,0 +1,7 @@ +export class X { + /** + * Instantiates X. + * @param prop The property of X. + */ + constructor(readonly prop: number) {} +} diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts index 67fc742df..1587e93f7 100644 --- a/src/test/issueTests.ts +++ b/src/test/issueTests.ts @@ -119,6 +119,14 @@ export const issueTests: { equal(Comment.combineDisplayParts(foo.comment?.summary), "Docs!"); }, + gh1261(project) { + const prop = query(project, "X.prop"); + equal( + Comment.combineDisplayParts(prop.comment?.summary), + "The property of X." + ); + }, + gh1330(project) { const example = query(project, "ExampleParam"); equal(example?.type?.type, "reference");