Fix #3070

Gerrit0 · Gerrit0 · commit 977c604e7857 · 2026-02-13T10:56:16.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,8 @@ title: Changelog
 - Improved handling of comments for type aliases which have been declaration merged with functions, #3064.
 - Fixed anchor link generation to members named `$`, #3065.
 - Corrected typing of the `plugin` option to permit functions, #3066.
+- Warnings about unused `@param` tags will now be properly suppressed when they come from declaration files and
+  the suppressCommentWarningsInDeclarationFiles option is enabled, #3070.
 - Fixed conversion of types referencing type parameters on functions, #3071.
 
 ### Thanks!
diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts
@@ -148,6 +148,9 @@ export class CommentPlugin extends ConverterComponent {
     @Option("defaultCategory")
     accessor defaultCategory!: string;
 
+    @Option("suppressCommentWarningsInDeclarationFiles")
+    accessor suppressCommentWarningsInDeclarationFiles!: boolean;
+
     private _excludeKinds: number | undefined;
     private get excludeNotDocumentedKinds(): number {
         this._excludeKinds ??= this.application.options
@@ -406,7 +409,8 @@ export class CommentPlugin extends ConverterComponent {
         if (reflection.comment) {
             if (
                 reflection.comment.label &&
-                !/[A-Z_][A-Z0-9_]/.test(reflection.comment.label)
+                !/[A-Z_][A-Z0-9_]/.test(reflection.comment.label) &&
+                !this.suppressCommentWarnings(reflection.comment)
             ) {
                 context.logger.warn(
                     i18n.label_0_for_1_cannot_be_referenced(
@@ -421,7 +425,7 @@ export class CommentPlugin extends ConverterComponent {
                     group,
                     reflection.comment.modifierTags,
                 );
-                if (intersect.size > 1) {
+                if (intersect.size > 1 && !this.suppressCommentWarnings(reflection.comment)) {
                     const [a, b] = intersect;
                     context.logger.warn(
                         i18n.modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2(
@@ -724,7 +728,7 @@ export class CommentPlugin extends ConverterComponent {
 
         moveNestedParamTags(/* in-out */ paramTags, params, comment.sourcePath);
 
-        if (!comment.inheritedFromParentDeclaration) {
+        if (!comment.inheritedFromParentDeclaration && !this.suppressCommentWarnings(comment)) {
             for (const tag of paramTags) {
                 this.application.logger.warn(
                     i18n.signature_0_has_unused_param_with_name_1(
@@ -735,6 +739,11 @@ export class CommentPlugin extends ConverterComponent {
             }
         }
     }
+
+    private suppressCommentWarnings(comment: Comment) {
+        return this.suppressCommentWarningsInDeclarationFiles &&
+            /\.d\.(ts|mts|cts)$/.test(comment.sourcePath || "");
+    }
 }
 
 function inTypeLiteral(refl: Reflection | undefined) {
diff --git a/src/lib/utils-common/path.ts b/src/lib/utils-common/path.ts
@@ -161,4 +161,8 @@ export namespace NormalizedPathUtils {
         }
         return { name: name.substring(0, lastDot), ext: name.substring(lastDot) };
     }
+
+    export function isDeclarationFilePath(path: NormalizedPath) {
+        return /\.d\.(ts|mts|cts)$/.test(path);
+    }
 }
diff --git a/src/test/converter2/issues/gh3070.ts b/src/test/converter2/issues/gh3070.ts
@@ -0,0 +1,3 @@
+export class NumberArray extends Array<number> {
+    foo() {}
+}
diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts
@@ -2304,6 +2304,12 @@ describe("Issue Tests", () => {
         equal(Comment.combineDisplayParts(project.children[1].signatures?.[0].comment?.summary), "B");
     });
 
+    it("#3070 does not warn due to bad comment in declaration file", () => {
+        app.options.setValue("excludeExternals", false);
+        app.options.setValue("suppressCommentWarningsInDeclarationFiles", true);
+        convert();
+    });
+
     it("#3071 correctly handles substitution types", () => {
         const project = convert();
         const m = querySig(project, "m");

Original file line number	Diff line number	Diff line change
`@@ -161,4 +161,8 @@ export namespace NormalizedPathUtils {`
`161`	`161`	`}`
`162`	`162`	`return { name: name.substring(0, lastDot), ext: name.substring(lastDot) };`
`163`	`163`	`}`
	`164`	`+`
	`165`	`+ export function isDeclarationFilePath(path: NormalizedPath) {`
	`166`	`+ return /\.d\.(ts\|mts\|cts)$/.test(path);`
	`167`	`+ }`
`164`	`168`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export class NumberArray extends Array<number> {`
	`2`	`+ foo() {}`
	`3`	`+}`