require-throws-tag

Require @throws tags for documented functions and methods that throw.

Targeted pattern scope

This rule checks documented functions/methods with block bodies and reports when they contain throw statements but no @throws (or @throw) tag.

What this rule reports

This rule reports missing throw documentation when a function body includes throw logic.

Why this rule exists

Exception behavior is critical API contract information. Missing @throws tags make error handling expectations unclear in generated docs.

❌ Incorrect

/**
 * Parse JSON content.
 * @param input JSON source.
 * @returns Parsed object.
 */
export function parseJson(input: string): unknown {
    if (input.length === 0) {
        throw new TypeError("Input must not be empty.");
    }

    return JSON.parse(input);
}

✅ Correct

/**
 * Parse JSON content.
 * @param input JSON source.
 * @returns Parsed object.
 * @throws {TypeError} When the input is empty.
 */
export function parseJson(input: string): unknown {
    if (input.length === 0) {
        throw new TypeError("Input must not be empty.");
    }

    return JSON.parse(input);
}

Behavior and migration notes

Autofix appends a TODO @throws line. Then replace the placeholder with concrete error semantics.

ESLint flat config example

import typedocPlugin from "eslint-plugin-typedoc";

export default [
    {
        plugins: { typedoc: typedocPlugin },
        rules: {
            "typedoc/require-throws-tag": "error",
        },
    },
];

When not to use it

Disable this rule if your team intentionally keeps throw semantics out of TypeDoc prose.

Package documentation

TypeDoc package documentation:

• TypeDoc @throws tag

Further reading

Rule catalog ID: R011

• TypeDoc comments and tags

Adoption resources

• Enable this in strict rollout stages after baseline doc completeness rules.