Skip to main content

Require JSDoc Body

Require a body paragraph in JSDoc blocks that explains why the declaration exists.

Summary

The require-jsdoc-body rule reports any JSDoc block that is missing a body paragraph after the summary line. The body paragraph must explain why the declaration exists and meet minimum and maximum line count and line width constraints.

Why Use This Rule?

  1. Forces authors to explain the purpose behind each declaration, not just restate its name.
  2. Catches JSDoc blocks that have a summary line but no context for future readers.
  3. Enforces consistent body length and width so inline documentation stays readable.

Examples

When diamond is enabled, a 3-line body must have its second (middle) line be the longest, forming a diamond or belly shape:

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
diamondbooleanfalseWhen enabled, a 3-line body must have its second (middle) line be the longest, forming a diamond shape.
ignoreFilesstring[][]File names to skip. Supports a leading-* suffix (*.test.ts), an exact path, or a trailing path segment; ** globs are not supported.
maxLinesnumber3Maximum number of lines allowed in the body.
maxWidthnumber80Maximum character width allowed per body line.
minLinesnumber2Minimum number of lines required in the body.
skipDirectoriesstring[][]Directory names to skip.

Autofix

Autofix is not available for this rule. Flagged code must be updated manually.

Troubleshooting

  • Warning fires even though a body is present — Check that the body paragraph is separated from the summary line by a blank * line. Text immediately after the summary is treated as part of the summary, not as body text.
  • Body too short or too long — Adjust minLines and maxLines to match your project's documentation standards.
  • Line too wide — The maxWidth option defaults to 80 characters per body line. Wrap long sentences to stay within the limit.
  • Want to skip specific files — Use the ignoreFiles option to exclude files that do not need body paragraphs.
  • Rule appears to do nothing — If maxLines is set lower than minLines, the rule disables itself for the whole file (no warnings are emitted). Ensure maxLines is greater than or equal to minLines.
  • Tags-only or empty JSDoc blocks are not flagged — The rule only checks blocks that have a summary line. A JSDoc block with no summary (empty, or containing only tags like @since) is skipped.
  • Diamond warning fires on a 3-line body — With diamond enabled, the second (middle) line must be the longest of the three. Rewrap the body so the middle line is longer than both the first and last.