Introduce preservedTypeAnnotationTags option

Resolves #3020

Total time spent: 32 minutes

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,12 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+- Introduced the `preservedTypeAnnotationTags` option to specify tags whose type annotations should
+  be copied to the output documentation, #3020.
+  API: Introduced `typeAnnotation` on `CommentTag`
+
 ## v0.28.13 (2025-09-14)
 
 ### Features

site/options/comments.md

@@ -190,7 +190,7 @@ Note that `@deprecated` is a block tag, not a modifier tag, so should not be spe
 ## excludeTags
 
 ```bash
-$ typedoc --excludeTags apidefine
+$ typedoc --excludeTags @apidefine
 ```
 
 Specify tags that should be removed from doc comments when parsing.
@@ -199,14 +199,26 @@ Useful if your project uses [apiDoc](https://apidocjs.com/) for documenting REST
 ## notRenderedTags
 
 ```bash
-$ typedoc --notRenderedTags beta
+$ typedoc --notRenderedTags @beta
 ```
 
 Specify tags which should be preserved in the doc comments, but not rendered
 when creating output. This is intended to support tags which carry some meaning
 about how to render a member or instructions for TypeDoc to do something after a
 package has been deserialized from JSON in packages mode.
 
+## preservedTypeAnnotationTags
+
+```json
+// typedoc.json
+{
+    "preservedTypeAnnotationTags": ["@fires"]
+}
+```
+
+Specify block tags whose type annotations should be preserved by TypeDoc's parser,
+leading to their content being included in the rendered documentation.
+
 ## externalSymbolLinkMappings
 
 ```json

site/options/package-options.md

@@ -121,6 +121,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`cascadedModifierTags`](comments.md#cascadedmodifiertags)                                           | Package  |                                                                             |
 | [`excludeTags`](comments.md#excludetags)                                                             | Package  |                                                                             |
 | [`notRenderedTags`](comments.md#notrenderedtags)                                                     | Root     |                                                                             |
+| [`preservedTypeAnnotationTags`](comments.md#preservedtypeannotationtags)                             | Package  |                                                                             |
 | [`externalSymbolLinkMappings`](comments.md#externalsymbollinkmappings)                               | Both     | Unresolved links are checked both when converting and when merging projects |
 
 ## Organization Options

src/lib/converter/comments/index.ts

@@ -19,6 +19,7 @@ export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
     modifierTags: Set<string>;
+    preservedTypeAnnotationTags: Set<string>;
     jsDocCompatibility: JsDocCompatibility;
     suppressCommentWarningsInDeclarationFiles: boolean;
     useTsLinkResolution: boolean;

src/lib/converter/comments/parser.ts

@@ -380,7 +380,22 @@ function blockTag(
     let content: CommentDisplayPart[];
     if (tagName === "@example") {
         return exampleBlock(comment, lexer, config, i18n, warning, files);
-    } else if (
+    }
+
+    let typeAnnotation: string | undefined;
+    if (
+        !lexer.done() &&
+        config.preservedTypeAnnotationTags.has(tagName)
+    ) {
+        if (lexer.peek().kind === TokenSyntaxKind.Text && /^\s+$/.test(lexer.peek().text)) {
+            lexer.take();
+        }
+        if (lexer.peek().kind === TokenSyntaxKind.TypeAnnotation) {
+            typeAnnotation = lexer.take().text;
+        }
+    }
+
+    if (
         ["@default", "@defaultValue"].includes(tagName) &&
         config.jsDocCompatibility.defaultTag
     ) {
@@ -396,7 +411,11 @@ function blockTag(
         content = blockContent(comment, lexer, config, i18n, warning, files);
     }
 
-    return new CommentTag(tagName as TagString, content);
+    const tag = new CommentTag(tagName as TagString, content);
+    if (typeAnnotation) {
+        tag.typeAnnotation = typeAnnotation;
+    }
+    return tag;
 }
 
 /**

src/lib/converter/converter.ts

@@ -785,12 +785,9 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
     private _buildCommentParserConfig() {
         this._config = {
             blockTags: new Set(this.application.options.getValue("blockTags")),
-            inlineTags: new Set(
-                this.application.options.getValue("inlineTags"),
-            ),
-            modifierTags: new Set(
-                this.application.options.getValue("modifierTags"),
-            ),
+            inlineTags: new Set(this.application.options.getValue("inlineTags")),
+            modifierTags: new Set(this.application.options.getValue("modifierTags")),
+            preservedTypeAnnotationTags: new Set(this.application.options.getValue("preservedTypeAnnotationTags")),
             jsDocCompatibility: this.application.options.getValue("jsDocCompatibility"),
             suppressCommentWarningsInDeclarationFiles: this.application.options.getValue(
                 "suppressCommentWarningsInDeclarationFiles",

src/lib/internationalization/locales/en.cts

@@ -316,6 +316,7 @@ export = {
     help_excludeTags: "Remove the listed block/modifier tags from doc comments",
     help_notRenderedTags: "Tags which will be preserved in doc comments, but not rendered when creating output",
     help_cascadedModifierTags: "Modifier tags which should be copied to all children of the parent reflection",
+    help_preservedTypeAnnotationTags: "Block tags whose type annotations should be preserved in the output.",
     help_readme:
         "Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page and start the documentation on the globals page",
     help_basePath: "Specifies a path which links may be resolved relative to.",

src/lib/models/Comment.ts

@@ -88,6 +88,12 @@ export class CommentTag {
      */
     name?: string;
 
+    /**
+     * Optional type annotation associated with this tag. TypeDoc will remove type annotations unless explicitly
+     * requested by the user with the `preservedTypeAnnotationTags` option.
+     */
+    typeAnnotation?: string;
+
     /**
      * The actual body text of this tag.
      */
@@ -130,6 +136,9 @@ export class CommentTag {
         if (this.name) {
             tag.name = this.name;
         }
+        if (this.typeAnnotation) {
+            tag.typeAnnotation = this.typeAnnotation;
+        }
         return tag;
     }
 
@@ -138,12 +147,14 @@ export class CommentTag {
             tag: this.tag,
             name: this.name,
             content: Comment.serializeDisplayParts(this.content),
+            typeAnnotation: this.typeAnnotation,
         };
     }
 
     fromObject(de: Deserializer, obj: JSONOutput.CommentTag) {
         // tag already set by Comment.fromObject
         this.name = obj.name;
+        this.typeAnnotation = obj.typeAnnotation;
         this.content = Comment.deserializeDisplayParts(de, obj.content);
     }
 }

src/lib/output/themes/default/partials/comment.tsx

@@ -83,6 +83,7 @@ export function commentTags(context: DefaultThemeRenderContext, props: Reflectio
                         {name}
                         {anchorIcon(context, anchor)}
                     </h4>
+                    {item.typeAnnotation && <span class="tsd-type-annotation">{item.typeAnnotation}</span>}
                     <JSX.Raw html={context.markdown(item.content)} />
                 </div>
             </>

src/lib/serialization/schema.ts

@@ -369,7 +369,7 @@ export interface Comment extends Partial<S<M.Comment, "blockTags" | "label">> {
 }
 
 /** @category Comments */
-export interface CommentTag extends S<M.CommentTag, "tag" | "name"> {
+export interface CommentTag extends S<M.CommentTag, "tag" | "name" | "typeAnnotation"> {
     content: CommentDisplayPart[];
 }