Skip to main content

Require JSDoc Returns

Require every @returns tag to contain only a type in braces, with no trailing description.

Summary

The require-jsdoc-returns rule reports any @returns tag that carries more than a braced type. A valid tag reads @returns {SomeType} and nothing else — never @returns {SomeType} the result or @returns void.

The semantic meaning of the return value lives in the named type alias, so the description belongs there rather than on the tag.

Why Use This Rule?

  1. Keeps every @returns tag terse and uniform, so readers get the type at a glance.
  2. Pushes the meaning into the named type alias, where it stays close to the shape it describes.
  3. Blocks bare types like @returns void that skip the braces, keeping the syntax consistent.

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

Autofix is not available for this rule. Flagged code must be updated manually by moving the description into the named type alias.

Troubleshooting

  • Warning fires on @returns {Config} the result — The trailing description is not allowed. Move it into the Config type alias and leave only @returns {Config}.
  • Warning fires on @returns void — The type must be wrapped in braces. Write @returns {void} instead.
  • Not sure where the description should go — Document the meaning of the return value on the named type alias it points to, not on the tag.
  • Want to skip specific files — Use the ignoreFiles option to exclude files where the type-only convention does not apply.