From 7c49a6df7bf0314b9ae6ea5d96a78a21c40ca112 Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Tue, 15 Feb 2022 22:04:21 -0700
Subject: [PATCH] Handle comments on destructured exported elements

Resolves #1770
---
 CHANGELOG.md                            |  1 +
 src/lib/converter/comments/discovery.ts | 21 +++++++++++++++++----
 src/test/converter2/issues/gh1770.ts    | 18 ++++++++++++++++++
 src/test/issueTests.ts                  | 14 ++++++++++++++
 4 files changed, 50 insertions(+), 4 deletions(-)
 create mode 100644 src/test/converter2/issues/gh1770.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89a493322..3389f933d 100644
--- 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
index 2b91d56fa..f8ec7140c 100644
--- 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
new file mode 100644
index 000000000..7ee8b4bc6
--- /dev/null
+++ 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
index 5f9e726cc..dcdd85cbd 100644
--- 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),