Conflict and warning when using `@decorator` tag with ESLint + TypeDoc "A tag is already defined using the name @decorator"

[marmoure]

Search terms

@decorator tsdoc, eslint-plugin-tsdoc, duplicate tag, unknown block tag, custom TSDoc tag conflict

Expected Behavior

TypeDoc should provide a supported workaround or extensibility mechanism for recognizing the @decorator tag, since it remains part of the official TSDoc specification:
https://tsdoc.org/pages/tags/decorator/

The TypeDoc team has explicitly stated that support for @decorator has been removed and will not be reintroduced.
However, projects that document decorators still need a reliable, functional solution that prevents warnings without modifying TypeDoc’s source.

TypeDoc should either:

• Offer a documented API or plugin hook to register and suppress warnings for custom tags like @decorator, or

• Accept a configuration-based extension (e.g., via typedoc.json) that can define tags safely without conflicts or warnings.

Actual Behavior

When documenting decorators, TypeDoc continues to emit:

[warning] Encountered an unknown block tag @decorator

even after implementing the suggested workaround from the maintainers:
#2346 (comment)

This indicates that the provided workaround no longer works as intended in current TypeDoc releases.

Steps to reproduce the bug

Create a simple TypeDoc project.

Add a @decorator tag:

/**
 * @decorator @makeComponent
 */
export class VideoNode {}

Run TypeDoc:

npx typedoc

We get: unknown block tag @decorator.
Apply the workaround described in
#2346 (comment)
Run again: the same warning still appears.

For a full picture you can check our lib: https://github.com/evolvedbinary/lwdita

Our Position

We use @decorator in our code documentation.

We understand and acknowledge that TypeDoc has removed support for this tag as stated in TypeStrong/typedoc#2346

We have applied the official workaround suggested in this comment

Despite following that guidance, TypeDoc continues to log:

[warning] Encountered an unknown block tag @decorator

We therefore need an updated, supported method for handling or suppressing @decorator warnings in TypeDoc 0.28+.

Environment

TypeDoc version: 0.28.14
TypeScript version: 5.9.3
Node.js version: 22.16.0
ESLint version: 9.38.0
eslint-plugin-tsdoc: 0.4.0
OS: Windows 10 x64 and CircleCI Linux

[Gerrit0]

There are two different things here.

The support which TypeDoc removed was for parsing real decorators and removing them from the output, not the tag. It predated support for real decorators and was never actually used by any of TypeDoc's code.

What you're after isn't support for TypeDoc parsing the actual decorator, but a tag within the comment, which can be done today by using the blockTags (or maybe modifierTags depending on how you expect it to be parsed) option to tell TypeDoc it exists, take a look at the defining tags documentation for another way you could do this.

[marmoure]

Thanks @Gerrit0 I did look into https://typedoc.org/documents/Options.Comments.html#modifiertags and that fixed my issue, previously all the solutions suggest we add a tsdoc.json :

{
    "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
    "extends": ["typedoc/tsdoc.json"],
    "tagDefinitions": [
        {
            "tagName": "@decorator",
            "syntaxKind": "block"
        }
    ]
}

this create a conflict with eslint.
here's my current setup for reference:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
  tsconfig: "./tsconfig.json",
  modifierTags: [...OptionDefaults.modifierTags, "@decorator"],
  highlightLanguages: ["ts", "js", "xml", "json", "bash"]
};

export default config;

I don't get any @decorator warnings nor conflict with eslint.