From 1357984ee012ca25b0422dd00f07572daa9aeaf1 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sun, 10 Apr 2022 15:21:56 -0600 Subject: [PATCH] Only take comments from exports for references and namespaces Ref: #1901 --- CHANGELOG.md | 3 +- src/lib/converter/comments/discovery.ts | 1 + src/lib/converter/context.ts | 24 +++++++++++--- src/lib/converter/symbols.ts | 14 +++----- src/test/behaviorTests.ts | 16 ++++++++++ src/test/converter/exports/specs.json | 32 +++++++++++++++++++ .../converter2/behavior/exportComments.ts | 13 ++++++++ 7 files changed, 88 insertions(+), 15 deletions(-) create mode 100644 src/test/converter2/behavior/exportComments.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index d489f839e..bfca3b706 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,7 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi - Listeners to `Converter.EVENT_CREATE_TYPE_PARAMETER` and `Converter.EVENT_CREATE_DECLARATION` will now never be passed a `ts.Node` as their third argument. - Constant variables which are interpreted as functions will no longer have the `ReflectionFlag.Const` flag set. - Removed deprecated `removeReaderByName`, `addDeclarations` and `removeDeclarationByName` methods on `Options`. +- Comments on export declarations will only overrides comments for references and namespaces, #1901. ### Features @@ -46,6 +47,7 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi - Improved comment discovery on destructured exported functions, #1770. - Links which refer to members within a reference reflection will now correctly resolve to the referenced reflection's member, #1770. - Correctly detect optional parameters in JavaScript projects using JSDoc, #1804. +- JS exports defined as `exports.foo = ...` will now be converted as variables rather than properties. ### Thanks! @@ -81,7 +83,6 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi - Fixed `removeReflection` not completely removing reflections from the project, #1898. - Fixed `@hidden` / `@ignore` / `@exclude` comments on default exports with no associated variable, #1903. - `makeRecursiveVisitor` will now correctly call the `intersection` callback, #1910. -- JS exports defined as `exports.foo = ...` will now be converted as variables rather than properties. ### Thanks! diff --git a/src/lib/converter/comments/discovery.ts b/src/lib/converter/comments/discovery.ts index e96c1a754..c290444e2 100644 --- a/src/lib/converter/comments/discovery.ts +++ b/src/lib/converter/comments/discovery.ts @@ -14,6 +14,7 @@ const wantedKinds: Record = { ts.SyntaxKind.ModuleDeclaration, ts.SyntaxKind.SourceFile, ts.SyntaxKind.BindingElement, + ts.SyntaxKind.ExportSpecifier, ], [ReflectionKind.Enum]: [ ts.SyntaxKind.EnumDeclaration, diff --git a/src/lib/converter/context.ts b/src/lib/converter/context.ts index 672545cd5..d8b501d5e 100644 --- a/src/lib/converter/context.ts +++ b/src/lib/converter/context.ts @@ -209,9 +209,23 @@ export class Context { const name = getHumanName( nameOverride ?? exportSymbol?.name ?? symbol?.name ?? "unknown" ); + const reflection = new DeclarationReflection(name, kind, this.scope); + this.postReflectionCreation(reflection, symbol, exportSymbol); - if (exportSymbol) { + return reflection; + } + + postReflectionCreation( + reflection: Reflection, + symbol: ts.Symbol | undefined, + exportSymbol: ts.Symbol | undefined + ) { + if ( + exportSymbol && + reflection.kind & + (ReflectionKind.SomeModule | ReflectionKind.Reference) + ) { reflection.comment = getComment( exportSymbol, reflection.kind, @@ -232,9 +246,11 @@ export class Context { reflection.setFlag(ReflectionFlag.Static); } - reflection.escapedName = symbol?.escapedName; + if (reflection instanceof DeclarationReflection) { + reflection.escapedName = symbol?.escapedName; + this.addChild(reflection); + } - this.addChild(reflection); if (symbol && this.converter.isExternal(symbol)) { reflection.setFlag(ReflectionFlag.External); } @@ -242,8 +258,6 @@ export class Context { this.registerReflection(reflection, exportSymbol); } this.registerReflection(reflection, symbol); - - return reflection; } finalizeDeclarationReflection(reflection: DeclarationReflection) { diff --git a/src/lib/converter/symbols.ts b/src/lib/converter/symbols.ts index a743eb6cb..5b10998eb 100644 --- a/src/lib/converter/symbols.ts +++ b/src/lib/converter/symbols.ts @@ -358,7 +358,7 @@ function createTypeParamReflection( defaultType, context.scope ); - context.registerReflection(paramRefl, param.symbol); + context.postReflectionCreation(paramRefl, param.symbol, void 0); context.trigger(ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl); return paramRefl; } @@ -753,10 +753,8 @@ function convertConstructSignatures(context: Context, symbol: ts.Symbol) { ReflectionKind.Constructor, context.scope ); - context.addChild(constructMember); - context.registerReflection(constructMember, symbol); - - context.trigger(ConverterEvents.CREATE_DECLARATION, constructMember); + context.postReflectionCreation(constructMember, symbol, void 0); + context.finalizeDeclarationReflection(constructMember); const constructContext = context.withScope(constructMember); @@ -802,10 +800,8 @@ function createAlias( target, context.scope ); - context.addChild(ref); - context.registerReflection(ref, symbol); - - context.trigger(ConverterEvents.CREATE_DECLARATION, ref); + context.postReflectionCreation(ref, symbol, exportSymbol); + context.finalizeDeclarationReflection(ref); } function convertVariable( diff --git a/src/test/behaviorTests.ts b/src/test/behaviorTests.ts index b9a90c7fe..240dd16b4 100644 --- a/src/test/behaviorTests.ts +++ b/src/test/behaviorTests.ts @@ -102,6 +102,22 @@ export const behaviorTests: Record< ]); }, + exportComments(project) { + const abc = query(project, "abc"); + equal(abc.kind, ReflectionKind.Variable); + equal(Comment.combineDisplayParts(abc.comment?.summary), "abc"); + + const abcRef = query(project, "abcRef"); + equal(abcRef.kind, ReflectionKind.Reference); + equal( + Comment.combineDisplayParts(abcRef.comment?.summary), + "export abc" + ); + + const foo = query(project, "foo"); + equal(Comment.combineDisplayParts(foo.comment?.summary), "export foo"); + }, + inheritDocBasic(project) { const target = query(project, "InterfaceTarget"); const comment = new Comment( diff --git a/src/test/converter/exports/specs.json b/src/test/converter/exports/specs.json index 9c0d25559..2557b4027 100644 --- a/src/test/converter/exports/specs.json +++ b/src/test/converter/exports/specs.json @@ -47,6 +47,14 @@ "kind": 16777216, "kindString": "Reference", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "This is a comment for Mod that overwrites the one specified in \"mod\"" + } + ] + }, "sources": [ { "fileName": "export.ts", @@ -107,6 +115,14 @@ "kind": 16777216, "kindString": "Reference", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "An export of a local under a different name." + } + ] + }, "sources": [ { "fileName": "mod.ts", @@ -657,6 +673,14 @@ "kind": 16777216, "kindString": "Reference", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "An export of a local under a different name." + } + ] + }, "sources": [ { "fileName": "mod.ts", @@ -672,6 +696,14 @@ "kind": 16777216, "kindString": "Reference", "flags": {}, + "comment": { + "summary": [ + { + "kind": "text", + "text": "An export with a module specifier that comes from this file." + } + ] + }, "sources": [ { "fileName": "mod.ts", diff --git a/src/test/converter2/behavior/exportComments.ts b/src/test/converter2/behavior/exportComments.ts new file mode 100644 index 000000000..03af8b78e --- /dev/null +++ b/src/test/converter2/behavior/exportComments.ts @@ -0,0 +1,13 @@ +/** abc */ +const abc = 123; + +/** export abc */ +export { abc, abc as abcRef }; + +/** foo */ +namespace foo { + export const abc = 123; +} + +/** export foo */ +export { foo };