Consider overload position when discovering comments

Resolves #2755

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 -   Fix support for ESM config files with Node 23, #2752.
 -   Fix type errors when using `"module": "ESNext"` and importing TypeDoc, #2747.
+-   Inherited comments on overloaded methods now consider the overload position when inheriting a comment, #2755.
 
 ## v0.26.10 (2024-10-16)
 

src/lib/converter/comments/discovery.ts

@@ -3,7 +3,7 @@ import { ReflectionKind } from "../../models";
 import { assertNever, type Logger } from "../../utils";
 import { CommentStyle } from "../../utils/options/declaration";
 import { nicePath } from "../../utils/paths";
-import { ok } from "assert";
+import assert, { ok } from "assert";
 import { filter, firstDefined } from "../../utils/array";
 
 const variablePropertyKinds = [
@@ -499,13 +499,33 @@ function declarationToCommentNodes(
             },
         ];
 
+    let overloadIndex: number | undefined = undefined;
+    if (ts.isMethodDeclaration(node)) {
+        const symbol = checker.getSymbolAtLocation(node.name || node);
+        if (symbol) {
+            overloadIndex = symbol.declarations
+                ?.filter((d) => d.kind === node.kind)
+                .indexOf(node);
+            assert(overloadIndex !== -1, "Should always find declaration");
+        }
+    }
+
     const seenSymbols = new Set<ts.Symbol>();
     const bases = findBaseOfDeclaration(checker, node, (symbol) => {
         if (!seenSymbols.has(symbol)) {
             seenSymbols.add(symbol);
-            return symbol.declarations?.map(
-                (node) => declarationToCommentNodeIgnoringParents(node) || node,
-            );
+            if (overloadIndex === undefined) {
+                return symbol.declarations?.map(
+                    (node) =>
+                        declarationToCommentNodeIgnoringParents(node) || node,
+                );
+            } else if (symbol.declarations?.[overloadIndex]) {
+                const parentSigNode = symbol.declarations[overloadIndex];
+                return [
+                    declarationToCommentNodeIgnoringParents(parentSigNode) ||
+                        parentSigNode,
+                ];
+            }
         }
     });
 

src/test/converter2/issues/gh2755.ts

@@ -0,0 +1,27 @@
+export interface Test {
+    /** A */
+    method(a: string): boolean;
+
+    /** B */
+    method(a: number): number;
+}
+
+export class Class implements Test {
+    method(a: string): boolean;
+    method(a: number): number;
+    method(a: string | number): number | boolean {
+        if (typeof a === "string") {
+            return false;
+        }
+        return 1;
+    }
+}
+
+export interface MultiCallSignature {
+    /** A */
+    (): string;
+    /** B */
+    (x: string): string;
+}
+
+export const Callable: MultiCallSignature = () => "";

src/test/issues.c2.test.ts

@@ -1798,4 +1798,16 @@ describe("Issue Tests", () => {
             { display: "Node", target: "https://typescriptlang.org" },
         ]);
     });
+
+    it("#2755 handles multiple signature when discovering inherited comments", () => {
+        const project = convert();
+        equal(getSigComment(project, "Test.method", 0), "A");
+        equal(getSigComment(project, "Test.method", 1), "B");
+
+        equal(getSigComment(project, "Class.method", 0), "A");
+        equal(getSigComment(project, "Class.method", 1), "B");
+
+        equal(getSigComment(project, "Callable", 0), "A");
+        equal(getSigComment(project, "Callable", 1), "B");
+    });
 });