Only take comments from exports for references and namespaces

Ref: #1901

Author: Gerrit0

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!
 

src/lib/converter/comments/discovery.ts

@@ -14,6 +14,7 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
         ts.SyntaxKind.ModuleDeclaration,
         ts.SyntaxKind.SourceFile,
         ts.SyntaxKind.BindingElement,
+        ts.SyntaxKind.ExportSpecifier,
     ],
     [ReflectionKind.Enum]: [
         ts.SyntaxKind.EnumDeclaration,

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,18 +246,18 @@ 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);
         }
         if (exportSymbol) {
             this.registerReflection(reflection, exportSymbol);
         }
         this.registerReflection(reflection, symbol);
-
-        return reflection;
     }
 
     finalizeDeclarationReflection(reflection: DeclarationReflection) {

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(

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(

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",

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 };