Skip to main content

require-jsdoc

Require JSDoc comments for configured declaration kinds.

Targeted pattern scope​

This rule checks declaration nodes that are configured via kinds, including:

  • function (FunctionDeclaration with an identifier)
  • class (ClassDeclaration with an identifier)
  • method (MethodDefinition, excluding constructors)
  • type (TSInterfaceDeclaration, TSTypeAliasDeclaration)
  • arrow-function (named const variable declarators initialized with an arrow function)

Each targeted declaration must have a leading JSDoc block comment (/** ... */).

What this rule reports​

This rule reports declarations of configured kinds when they do not have a leading JSDoc block comment.

Why this rule exists​

When teams rely on declarations as API boundaries, missing JSDoc usually means missing intent, missing parameter semantics, and inconsistent generated docs. This rule enforces baseline documentation hygiene for selected declaration kinds.

❌ Incorrect​

function f() {}

with options:

{
 kinds: ["function"];
}

✅ Correct​

/**
 * Convert a domain identifier into a cache key.
 */
function f() {}

with options:

{
 kinds: ["function"];
}

Deprecated​

  • Lifecycle: Deprecated and frozen.
  • Deprecated since: v1.0.0
  • Available until: v4.0.0
  • Use instead: jsdoc/require-jsdoc

Behavior and migration notes​

This rule does not auto-fix because it cannot infer accurate documentation text.

For large repositories, start with a narrower kinds set (for example only function and class), then add method, type, and arrow-function after the initial backlog is resolved.

Options​

type Kind = "arrow-function" | "class" | "function" | "method" | "type";

type Options = [
 {
  kinds?: Kind[];
 },
];

Default configuration​

[
 {
  kinds: ["arrow-function", "class", "function", "method", "type"],
 },
];

Status​

  • Lifecycle: Deprecated and frozen.
  • Deprecated since: v1.0.0
  • Available until: v4.0.0
  • Use instead: jsdoc/require-jsdoc

Additional examples​

const identity = <T>(value: T) => value;

with options:

{
 kinds: ["arrow-function"];
}
/**
 * Return the input value unchanged.
 */
const identity = <T>(value: T) => value;

ESLint flat config example​

import etcMisc from "eslint-plugin-etc-misc";

export default [
 {
  plugins: { "etc-misc": etcMisc },
  rules: {
   "etc-misc/require-jsdoc": ["error", { kinds: ["function"] }],
  },
 },
];

When not to use it​

Disable this rule if your project uses external documentation sources (for example ADRs or API schema files) and intentionally avoids inline JSDoc.

Package documentation​

Rule catalog ID: R083

Further reading​

Adoption resources​

  • Start at warning level in CI, then move to error after cleanup.
  • Use focused codemods/autofix batches per package or directory.