Skip to content
Complete LogoComplete

complete/format-jsdoc-comments

💼 This rule is enabled in the ✅ recommended config.

📝 Disallows /** comments longer than N characters and multi-line comments that can be merged together.

🔧 This rule is automatically fixable by the --fix CLI option.

⚙️ This rule is configurable.

Much like Prettier, this rule is designed to auto-format your comments so that you don’t have to think about it. Try configuring your IDE to run eslint --fix on save.

Also see the format-line-comments rule.

For more information on why you should use this rule, see the comment formatting discussion.

Rule Details

Section titled “Rule Details”

Lines that are too long will be split to the next line:

// Bad
/**
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 */


// Good
/**
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
 * labore et dolore magna aliqua.
 */

Similarly, lines that are too long in a single-line JSDoc will be converted to a multi-line JSDoc:

// Bad
/** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. */


// Good
/**
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
 * labore et dolore magna aliqua.
 */

Lines that are too short will be merged together. And, if possible, JSDoc will be converted to a single-line:

// Bad
/**
 * I love cookies.
 * But not cake.
 */


// Good
/** I love cookies. But not cake. */

The rule tries to be as smart as possible. For example, it won’t complain about a bulleted list:

// Good
/**
 * These are my favorite things:
 * - cookies
 * - pie
 * - definitely not cake
 */

You can open a GitHub issue if you find a situation where this rule should be smarter.

Non JSDoc-style comments (i.e., lines that begin with /* followed by a space) are ignored, since they are commonly-used to comment-out large blocks of code.

For example:

/* This is a single-line comment. This is a single-line comment. This is a single-line comment. This is a single-line comment. */

Options

Section titled “Options”
{
  "rules": {
    "complete/format-jsdoc-comments": [
      "error",
      {
        "maxLength": 100
      }
    ]
  }
}

Resources

Section titled “Resources”