Skip to main content

no-unknown-tags

Disallow unknown TypeDoc tags and normalize common alias tags.

Targeted pattern scopeโ€‹

This rule checks @tag markers in TypeDoc block comments and compares them to TypeDoc's built-in supported block, inline, modifier, and TypeScript-compatibility tag set.

What this rule reportsโ€‹

This rule reports tags that are not recognized by TypeDoc's built-in supported tag set.

It also autofixes common aliases such as:

  • @return -> @returns
  • @arg -> @param
  • @argument -> @param

Why this rule existsโ€‹

Unknown tags are easy to miss during review and often result in incomplete or misleading generated docs. Reporting them at lint time keeps documentation semantics consistent.

This is especially important for JSDoc-oriented codebases, because TypeDoc intentionally supports only a subset of the broader JSDoc ecosystem.

โŒ Incorrectโ€‹

/**
 * @return The normalized output.
 */
export function normalize(value: string): string {
    return value.trim();
}
/**
 * @foo Unsupported custom tag.
 */
export function run(): void {}

โœ… Correctโ€‹

/**
 * @returns The normalized output.
 */
export function normalize(value: string): string {
    return value.trim();
}

Behavior and migration notesโ€‹

Use autofix for known aliases, then manually resolve any remaining unknown tags to valid TypeDoc tags.

additionalTags optionโ€‹

You can extend the built-in allowed tag set with the additionalTags option. This is the primary escape hatch for projects that define extra tags via TypeDoc plugins or a tsdoc.json configuration file.

// eslint.config.mjs
{
    "typedoc/no-unknown-tags": [
        "error",
        { "additionalTags": ["customTag", "myPluginTag"] }
    ]
}

In TypeScript flat config:

import typedocPlugin from "eslint-plugin-typedoc";

export default [
    {
        plugins: { typedoc: typedocPlugin },
        rules: {
            "typedoc/no-unknown-tags": [
                "error",
                { additionalTags: ["customTag", "myPluginTag"] },
            ],
        },
    },
];

ESLint flat config exampleโ€‹

import typedocPlugin from "eslint-plugin-typedoc";

export default [
    {
        plugins: { typedoc: typedocPlugin },
        rules: {
            "typedoc/no-unknown-tags": "error",
        },
    },
];

When not to use itโ€‹

Disable this rule only when your team intentionally uses custom non-TypeDoc tags and accepts that generated docs may ignore them. Prefer the additionalTags option over disabling the rule entirely.

Package documentationโ€‹

TypeDoc package documentation:

Further readingโ€‹

Rule catalog ID: R002

Adoption resourcesโ€‹

  • Run this rule with --fix first to normalize common alias tags across large codebases.
  • If you need configurable enforcement for required comments or required tags, pair this plugin with eslint-plugin-tsdoc-require-2.