Extend jsDocCompatibility with inheritDoc + brace opts

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 -   Improved error messaging if a provided entry point could not be converted into a documented module reflection, #2242.
 -   API: Added support for `g`, `circle`, `ellipse`, `polygon`, and `polyline` svg elements, #2259.
+-   Extended `jsDocCompatibility` option with `inheritDocTag` to ignore fully lowercase `inheritDoc` tags and
+    `ignoreUnescapedBraces` to disable warnings about unescaped `{` and `}` characters in comments.
 
 ### Bug Fixes
 

src/lib/converter/comments/parser.ts

@@ -342,10 +342,12 @@ function blockContent(
 
             case TokenSyntaxKind.Tag:
                 if (next.text === "@inheritdoc") {
-                    warning(
-                        "The @inheritDoc tag should be properly capitalized",
-                        next
-                    );
+                    if (!config.jsDocCompatibility.inheritDocTag) {
+                        warning(
+                            "The @inheritDoc tag should be properly capitalized",
+                            next
+                        );
+                    }
                     next.text = "@inheritDoc";
                 }
                 if (config.modifierTags.has(next.text)) {
@@ -371,7 +373,9 @@ function blockContent(
 
             case TokenSyntaxKind.CloseBrace:
                 // Unmatched closing brace, generate a warning, and treat it as text.
-                warning(`Unmatched closing brace`, next);
+                if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
+                    warning(`Unmatched closing brace`, next);
+                }
                 content.push({ kind: "text", text: next.text });
                 break;
 
@@ -433,10 +437,12 @@ function inlineTag(
         lexer.done() ||
         ![TokenSyntaxKind.Text, TokenSyntaxKind.Tag].includes(lexer.peek().kind)
     ) {
-        warning(
-            "Encountered an unescaped open brace without an inline tag",
-            openBrace
-        );
+        if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
+            warning(
+                "Encountered an unescaped open brace without an inline tag",
+                openBrace
+            );
+        }
         block.push({ kind: "text", text: openBrace.text });
         return;
     }
@@ -449,10 +455,12 @@ function inlineTag(
             (!/^\s+$/.test(tagName.text) ||
                 lexer.peek().kind != TokenSyntaxKind.Tag))
     ) {
-        warning(
-            "Encountered an unescaped open brace without an inline tag",
-            openBrace
-        );
+        if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
+            warning(
+                "Encountered an unescaped open brace without an inline tag",
+                openBrace
+            );
+        }
         block.push({ kind: "text", text: openBrace.text + tagName.text });
         return;
     }

src/lib/utils/options/declaration.ts

@@ -222,6 +222,16 @@ export type JsDocCompatibility = {
      * On by default, this is how VSCode renders blocks.
      */
     defaultTag: boolean;
+    /**
+     * If set, TypeDoc will warn if a `@inheritDoc` tag is spelled without TSDoc capitalization
+     * (i.e. `@inheritdoc`). On by default.
+     */
+    inheritDocTag: boolean;
+    /**
+     * If set, TypeDoc will not emit warnings about unescaped `{` and `}` characters encountered
+     * when parsing a comment. On by default.
+     */
+    ignoreUnescapedBraces: boolean;
 };
 
 /**

src/lib/utils/options/sources/typedoc.ts

@@ -530,6 +530,8 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         defaults: {
             defaultTag: true,
             exampleTag: true,
+            inheritDocTag: true,
+            ignoreUnescapedBraces: true,
         },
     });