require-package-documentation-description

Require top-level @packageDocumentation comments to include descriptive prose.

Targeted pattern scope

This rule checks exporting modules that already have a package-level TypeDoc comment.

What this rule reports

This rule reports package documentation blocks that contain only the tag and no meaningful description text.

Why this rule exists

A bare package tag without explanatory prose adds little value to generated docs. Modules should explain what the exported API is for.

❌ Incorrect

/**
 * @packageDocumentation
 */

export function add(left: number, right: number): number {
    return left + right;
}

✅ Correct

/**
 * @packageDocumentation
 * Public API helpers for parsing values.
 */

export function add(left: number, right: number): number {
    return left + right;
}

Behavior and migration notes

This rule intentionally does not autofix because module descriptions should be written intentionally.

ESLint flat config example

import typedocPlugin from "eslint-plugin-typedoc";

export default [
    {
        plugins: { typedoc: typedocPlugin },
        rules: {
            "typedoc/require-package-documentation-description": "error",
        },
    },
];

When not to use it

Disable when package-level descriptions are intentionally managed elsewhere.

Package documentation

TypeDoc package documentation:

• TypeDoc @packageDocumentation tag

Further reading

Rule catalog ID: R023

• TypeDoc comments and tags

Adoption resources

• Use alongside require-package-documentation and prefer-package-documentation-tag for package-doc quality.