From 657eb4bdae1ac6d9e897bcdb4567d9876f3f6338 Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Sun, 23 Jun 2024 07:10:34 -0600
Subject: [PATCH] Add suppressCommentWarningsInDeclarationFiles option

Resolves #2611
---
 CHANGELOG.md                             |  5 +++++
 src/lib/converter/comments/index.ts      |  1 +
 src/lib/converter/comments/parser.ts     |  7 +++++++
 src/lib/converter/converter.ts           |  4 ++++
 src/lib/utils/options/declaration.ts     |  1 +
 src/lib/utils/options/sources/typedoc.ts |  6 ++++++
 src/test/comments.test.ts                |  1 +
 src/test/converter2/issues/gh2611.d.ts   |  4 ++++
 src/test/issues.c2.test.ts               | 13 +++++++++++++
 9 files changed, 42 insertions(+)
 create mode 100644 src/test/converter2/issues/gh2611.d.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef7d0c022..8624e486e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Unreleased
 
+### Features
+
+-   Added a `--suppressCommentWarningsInDeclarationFiles` option to disable warnings from
+    parsing comments in declaration files, #2611.
+
 ### Bug Fixes
 
 -   The `text` non-highlighted language no longer causes warnings when rendering, #2610.
diff --git a/src/lib/converter/comments/index.ts b/src/lib/converter/comments/index.ts
index cec00639d..09614a7c8 100644
--- a/src/lib/converter/comments/index.ts
+++ b/src/lib/converter/comments/index.ts
@@ -22,6 +22,7 @@ export interface CommentParserConfig {
     inlineTags: Set<string>;
     modifierTags: Set<string>;
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
 }
 
 const jsDocCommentKinds = [
diff --git a/src/lib/converter/comments/parser.ts b/src/lib/converter/comments/parser.ts
index 793e11583..af65774ea 100644
--- a/src/lib/converter/comments/parser.ts
+++ b/src/lib/converter/comments/parser.ts
@@ -109,6 +109,12 @@ export function parseComment(
     return comment;
 
     function warningImpl(message: TranslatedString, token: Token) {
+        if (
+            config.suppressCommentWarningsInDeclarationFiles &&
+            file.fileName.endsWith(".d.ts")
+        ) {
+            return;
+        }
         logger.warn(message, token.pos, file);
     }
 }
@@ -135,6 +141,7 @@ export function parseCommentString(
             ignoreUnescapedBraces: true,
             inheritDocTag: true,
         },
+        suppressCommentWarningsInDeclarationFiles: true,
     };
 
     const reentry = new TextParserReentryState();
diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts
index 7743e1417..26722d372 100644
--- a/src/lib/converter/converter.ts
+++ b/src/lib/converter/converter.ts
@@ -693,6 +693,10 @@ export class Converter extends ChildableComponent<
             ),
             jsDocCompatibility:
                 this.application.options.getValue("jsDocCompatibility"),
+            suppressCommentWarningsInDeclarationFiles:
+                this.application.options.getValue(
+                    "suppressCommentWarningsInDeclarationFiles",
+                ),
         };
 
         // Can't be included in options because the TSDoc parser blows up if we do.
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
index be0f58959..bc73e1d06 100644
--- a/src/lib/utils/options/declaration.ts
+++ b/src/lib/utils/options/declaration.ts
@@ -196,6 +196,7 @@ export interface TypeDocOptionMap {
     useTsLinkResolution: boolean;
     preserveLinkText: boolean;
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];
     modifierTags: `@${string}`[];
diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
index d403471ee..2f6d02e8f 100644
--- a/src/lib/utils/options/sources/typedoc.ts
+++ b/src/lib/utils/options/sources/typedoc.ts
@@ -685,6 +685,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         },
     });
 
+    options.addDeclaration({
+        name: "suppressCommentWarningsInDeclarationFiles",
+        help: (i18n) => i18n.help_lang(),
+        type: ParameterType.Boolean,
+    });
+
     options.addDeclaration({
         name: "commentStyle",
         help: (i18n) => i18n.help_commentStyle(),
diff --git a/src/test/comments.test.ts b/src/test/comments.test.ts
index 61c39d2d9..734f0d7ef 100644
--- a/src/test/comments.test.ts
+++ b/src/test/comments.test.ts
@@ -1094,6 +1094,7 @@ describe("Comment Parser", () => {
             ignoreUnescapedBraces: false,
             inheritDocTag: false,
         },
+        suppressCommentWarningsInDeclarationFiles: false,
     };
 
     it("Should recognize @defaultValue as code", () => {
diff --git a/src/test/converter2/issues/gh2611.d.ts b/src/test/converter2/issues/gh2611.d.ts
new file mode 100644
index 000000000..03ca47322
--- /dev/null
+++ b/src/test/converter2/issues/gh2611.d.ts
@@ -0,0 +1,4 @@
+/**
+ * @tagThatIsNotDefined
+ */
+export var num: number;
diff --git a/src/test/issues.c2.test.ts b/src/test/issues.c2.test.ts
index 81f579a80..5c210681e 100644
--- a/src/test/issues.c2.test.ts
+++ b/src/test/issues.c2.test.ts
@@ -1589,4 +1589,17 @@ describe("Issue Tests", () => {
 
         logger.expectNoOtherMessages();
     });
+
+    it("#2611 can suppress warnings from comments in declaration files", () => {
+        convert();
+        logger.expectMessage(
+            "warn: Encountered an unknown block tag @tagThatIsNotDefined",
+        );
+        logger.expectNoOtherMessages();
+        logger.reset();
+
+        app.options.setValue("suppressCommentWarningsInDeclarationFiles", true);
+        convert();
+        logger.expectNoOtherMessages();
+    });
 });