Add suppressCommentWarningsInDeclarationFiles option

Resolves #2611

Author: Gerrit0

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.

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 = [

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();

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.

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}`[];

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(),

src/test/comments.test.ts

@@ -1094,6 +1094,7 @@ describe("Comment Parser", () => {
             ignoreUnescapedBraces: false,
             inheritDocTag: false,
         },
+        suppressCommentWarningsInDeclarationFiles: false,
     };
 
     it("Should recognize @defaultValue as code", () => {

src/test/converter2/issues/gh2611.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @tagThatIsNotDefined
+ */
+export var num: number;

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();
+    });
 });