Handle comments on destructured exported elements

Resolves #1770
TypeStrong · Feb 16, 2022 · 7c49a6d · 7c49a6d
1 parent f3402fc
commit 7c49a6d
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,7 @@
 -   Fixed off by one error in warnings for types referenced but not included in the documentation.
 -   TypeDoc will no longer render a `Type Parameters` heading if there are no type parameters in some cases.
 -   Improved source location detection for constructors.
+-   Improved comment discovery on destructured exported functions, #1770.
 
 ## v0.22.11 (2022-01-18)
 

diff --git a/src/lib/converter/comments/discovery.ts b/src/lib/converter/comments/discovery.ts
@@ -13,6 +13,7 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
     [ReflectionKind.Namespace]: [
         ts.SyntaxKind.ModuleDeclaration,
         ts.SyntaxKind.SourceFile,
+        ts.SyntaxKind.BindingElement,
     ],
     [ReflectionKind.Enum]: [
         ts.SyntaxKind.EnumDeclaration,
@@ -23,9 +24,18 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
         // This is here so that @enum gets it
         ts.SyntaxKind.PropertyAssignment,
     ],
-    [ReflectionKind.Variable]: [ts.SyntaxKind.VariableDeclaration],
-    [ReflectionKind.Function]: [ts.SyntaxKind.FunctionDeclaration],
-    [ReflectionKind.Class]: [ts.SyntaxKind.ClassDeclaration],
+    [ReflectionKind.Variable]: [
+        ts.SyntaxKind.VariableDeclaration,
+        ts.SyntaxKind.BindingElement,
+    ],
+    [ReflectionKind.Function]: [
+        ts.SyntaxKind.FunctionDeclaration,
+        ts.SyntaxKind.BindingElement,
+    ],
+    [ReflectionKind.Class]: [
+        ts.SyntaxKind.ClassDeclaration,
+        ts.SyntaxKind.BindingElement,
+    ],
     [ReflectionKind.Interface]: [ts.SyntaxKind.InterfaceDeclaration],
     [ReflectionKind.Constructor]: [ts.SyntaxKind.Constructor],
     [ReflectionKind.Property]: [
@@ -88,9 +98,12 @@ export function discoverComment(
             // Special behavior here! We temporarily put the implementation comment
             // on the reflection which contains all the signatures. This lets us pull
             // the comment on the implementation if some signature does not have a comment.
+            // However, we don't want to skip the node if it is a reference to something.
+            // See the gh1770 test for an example.
             if (
                 kind & ReflectionKind.ContainsCallSignatures &&
-                !(node as ts.FunctionDeclaration).body
+                !(node as ts.FunctionDeclaration).body &&
+                node.kind !== ts.SyntaxKind.BindingElement
             ) {
                 continue;
             }

diff --git a/src/test/converter2/issues/gh1770.ts b/src/test/converter2/issues/gh1770.ts
@@ -0,0 +1,18 @@
+const api = (): {
+    sym1: () => number;
+    sym2: number;
+} => {
+    return null!;
+};
+
+export const {
+    /**
+     * Docs for Sym1
+     */
+    sym1,
+
+    /**
+     * Docs for Sym2
+     */
+    sym2,
+} = api();
diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts
@@ -331,6 +331,20 @@ export const issueTests: {
         );
     },
 
+    gh1770(project) {
+        const sym1 = query(project, "sym1");
+        equal(
+            Comment.combineDisplayParts(sym1.signatures?.[0].comment?.summary),
+            "Docs for Sym1"
+        );
+
+        const sym2 = query(project, "sym2");
+        equal(
+            Comment.combineDisplayParts(sym2.comment?.summary),
+            "Docs for Sym2"
+        );
+    },
+
     gh1795(project) {
         equal(
             project.children?.map((c) => c.name),