Skip to main content

Require JSDoc Param Alignment

Require vertical alignment of @param types, names, and dashes in JSDoc blocks.

Summary

The require-jsdoc-param-alignment rule reports any JSDoc block where two or more @param tags have misaligned columns.

The rule checks that all parameter names start at the same column and all dashes start at the same column. Blocks with zero or one @param tag are skipped.

Why Use This Rule?

  1. Makes multi-parameter JSDoc blocks easier to scan by aligning types, names, and descriptions into columns.
  2. Enforces a consistent visual format across all JSDoc documentation.
  3. Catches accidental misalignment that happens during refactoring or parameter renaming.

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
ignoreFilesstring[][]File names to skip. Supports a leading-* suffix (*.test.ts), an exact path, or a trailing path segment; ** globs are not supported.

Autofix

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

bash
npx eslint --fix . --rule '@cbnventures/nova/require-jsdoc-param-alignment: error'

Troubleshooting

  • Warning fires but alignment looks correct visually — The rule checks character positions, not visual width. If you use a non-monospace font in your editor, the columns may appear aligned but differ in character count. Switch to a monospace font to verify.
  • Single-param blocks are not checked — The rule only fires when a JSDoc block has two or more @param tags. Single-parameter blocks are skipped because there is nothing to align against.
  • Rule never fires on my multi-param block — Only @param lines written as @param {Type} name - description are counted; a line is ignored unless it has all three of a {type} in braces, a name, and a - dash. A block needs at least two such lines to be checked, so two @param tags that lack a type or lack a dash are not aligned.