Skip to main content

Require JSDoc Returns

Require documented functions to declare an @returns tag containing only a type in braces.

Summary

The require-jsdoc-returns rule reports a documented function when its JSDoc omits @returns. It also 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.

Constructors and setters are exempt because they cannot declare a return value. Missing JSDoc remains the responsibility of require-jsdoc-presence, while the semantic meaning of a return value lives in its named type alias.

Why Use This Rule?

  1. Prevents documented functions from silently omitting their return contract.
  2. Keeps every @returns tag terse and uniform, so readers get the type at a glance.
  3. Pushes the meaning into the named type alias, where it stays close to the shape it describes.
  4. 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. Add the missing type-only tag manually, or move a trailing description into the named type alias.

Troubleshooting

  • Warning reports a missing @returns tag — Add the function's named return type as @returns {SomeType}. Constructors and setters are exempt.
  • 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.