eslint-plugin-jsdoc

The jsdoc/no-missing-syntax rule reports when specific, expected JSDoc comment structures are missing from certain AST contexts. It allows you to validate that arbitrary structures (like specific tags or types) exist above specific code elements (like function declarations or variable assignments).

This rule is useful for:

• Enforcing specific documentation requirements in certain directories using ESLint overrides.
• Requiring @type or other tags to ensure code can be compiled (e.g., to WebAssembly via AssemblyScript).
• Validating that certain patterns (like @private or @enum) are always accompanied by the correct JSDoc block.

Unlike similar rules in other plugins, this rule always looks for a comment above a structure, regardless of whether a comment condition is specified.

The check-examples rule ensures that JavaScript samples within @example tags adhere to your project's ESLint rules. It can also be configured to lint default values in @param, @arg, @argument, @property, @prop, or @default tags.

Important Compatibility Note: This rule only works in ESLint 7. For ESLint 9, you must use the processors instead.

The @next tag is a non-standard JSDoc tag used to indicate the type/description of the value supplied to an iterator via .next(value).

When the next: true option is enabled, the rule requires that any function using @next contains a yield statement that captures a return value, such as const rv = yield; or const rv = yield value;. It will report an error if the body only contains plain yield; or yield value; statements without assignment.

/**
 * @next {SomeType}
 */
function * quux (foo) {
  const a = yield; // Required when next: true is enabled
}

The type-formatting rule is used to format JSDoc type values.

Warning: This rule is experimental. The stringification process might not preserve all aspects of your original formatting and could potentially introduce errors.

This rule can be configured via a single options object containing various properties to control spacing, brackets, quotes, and separators within JSDoc types.

You can configure the rule to skip parameter checks in specific scenarios:

1. By Tag: Use exemptedBy: ['type'] to ignore functions that are documented via @type instead of @param.
2. By Interface: If interfaceExemptsParamsCheck is true, functions whose types are defined by an interface (e.g., const quux: FunctionInterface = ...) will not be checked for parameters.
3. By Context: Use contexts to target specific AST nodes like ArrowFunctionExpression or TSFunctionType.

/** @type {MyCallback} */
function quux () {

}
// "jsdoc/require-param": ["error"|"warn", {"exemptedBy":["type"]}]

/**
 *
 */
const quux: FunctionInterface = function quux (foo) {
};
// "jsdoc/require-param": ["error"|"warn", {"interfaceExemptsParamsCheck":true}]

The contexts option allows you to limit where the rule is applied. This is useful if you only want to enforce description rules on certain structures like class properties or TypeScript interfaces.

Commonly used contexts:

• PropertyDefinition: For class fields.
• TSInterfaceDeclaration: For TypeScript interfaces.
• any: To apply to all contexts.

You can also use complex selector objects for fine-grained control over which JSDoc blocks are targeted.

Many rules in eslint-plugin-jsdoc are marked as fixable, meaning they can be automatically corrected by running ESLint with the --fix flag.

Some fixable rules include an enableFixer option:

• Set enableFixer: false to disable the automatic fixer for a specific rule.
• For rules like check-param-names, check-property-names, and no-blank-blocks, setting enableFixer: true enables a fixer that is not enabled by default in the recommended configuration.

If you use custom JSDoc tags, you can use the settings.jsdoc.structuredTags setting to tell the no-undefined-types rule how to treat them:

• To make a tag's name act as a definition (preventing it from being reported as undefined elsewhere), set its name to a value that indicates it is "name-defining" or "namepath-defining".
• To prevent the rule from checking the type of a specific tag, set its type to false.
• To define specific types that a tag's name refers to, set type to an array of strings.

The rule's behavior changes significantly based on the descriptionStyle option:

Style: body (Default)

Requires text directly in the JSDoc block. Using only a @description tag without preceding text will fail.

/**
 * This is a valid body description.
 */
function foo() {}

/**
 * @description This will fail if style is 'body'
 */
function bar() {}

Style: tag

Requires the @description or @desc tag. Implicit text in the body is not sufficient.

/**
 * @description This is valid for 'tag' style.
 */
function foo() {}

/**
 * This will fail if style is 'tag'
 */
function bar() {}

Style: any

Accepts both implicit body text and the @description tag.