Skip to main content

Require JSDoc Tag Order

Require JSDoc tags to follow the canonical order with exactly one blank line between adjacent tag groups.

Summary

The require-jsdoc-tag-order rule reports any JSDoc block whose tags are out of order or whose tag groups are spaced incorrectly. The canonical order is the title, prose body, then @param (grouped), @private, @returns, @since, and @deprecated.

Adjacent tag groups must be separated by exactly one blank line, and @param lines within their group must have no blank line between them. Notably, @private sits after the @param group and before @returns.

Why Use This Rule?

  1. Keeps every JSDoc block laid out the same way so readers scan tags in a predictable order.
  2. Normalizes the blank-line spacing between groups so blocks stay visually consistent across the codebase.
  3. Fixes both ordering and spacing automatically, so authors never have to reshuffle tags by hand.

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-tag-order: error'

The fix reorders the tags into canonical order and normalizes the blank-line spacing between groups, preserving the block's indentation.

Troubleshooting

  • @private appears in the wrong place — The canonical order places @private after the @param group and before @returns. Run the fixer to move it.
  • Blank line between two @param lines — Lines within the @param group must be adjacent with no blank line. The fixer removes the extra spacing.
  • Groups run together — Adjacent tag groups need exactly one blank * line between them. The fixer inserts the missing separator.
  • Want to skip specific files — Use the ignoreFiles option to exclude files that do not follow the canonical tag order.