Skip to main content

Require JSDoc Hierarchy

Require JSDoc summary lines to follow the hierarchy chain derived from the file path and method name.

Summary

The require-jsdoc-hierarchy rule reports any JSDoc summary line on a class or method that does not match the expected hierarchy string.

The expected hierarchy is built from the file path segments after the first matching anchor directory (default: src), with each segment title-cased and separated by -. For methods, the method name is appended as the final segment. Known abbreviations (e.g., api to API, eslint to ESLint) are applied automatically.

Why Use This Rule?

  1. Ensures every JSDoc summary line is consistent and predictable across the codebase.
  2. Makes it possible to locate a class or method in the file tree by reading its JSDoc summary.
  3. Eliminates subjective or inconsistent summary text by deriving it mechanically from the file path.

Examples

Configuration

Options

warning

ignoreFiles is an escape hatch for files where this rule genuinely does not apply. It is not intended for routine use.

OptionTypeDefaultDescription
anchorDirectoriesstring[]['src']Directory names that serve as path anchors.
ignoreFilesstring[][]File patterns to skip.
knownNamesRecord<string, string>{}Custom brand/abbreviation mappings for prettifying.
stripDirectoriesstring[]['types']Directory names to filter out from path parts.

Autofix

This rule provides automatic fixes. Run ESLint with the --fix flag:

npx eslint --fix . --rule '@cbnventures/nova/require-jsdoc-hierarchy: error'

Troubleshooting

  • Warning fires even though the summary looks correct — Check for extra or missing spaces around - separators, and verify that known abbreviations match exactly (e.g., API not Api, ESLint not Eslint).
  • File is not under any anchor directory — The rule tries each anchorDirectories entry in order. If none match, it falls back to using the filename stem as the hierarchy base (e.g., sidebars.ts becomes Sidebars.).
  • Constructors are not checked — The rule skips constructor methods intentionally.