eslint-plugin-jsdoc

JSDoc linting rules for ESLint.

• eslint-plugin-jsdoc
  • Installation
  • Configuration
    • Flat config (procedural)
    • Flat config (declarative)
    • eslintrc
  • Options
  • Settings
  • Advanced
  • Processors
  • Rules

Installation

Install ESLint either locally or globally.

npm install --save-dev eslint

If you have installed ESLint globally, you have to install JSDoc plugin globally too. Otherwise, install it locally.

npm install --save-dev eslint-plugin-jsdoc

Configuration

Flat config (procedural)

This is the currently recommended approach for all flat configs (besides the array-based examples, default-expressions, and examples-and-default-expressions configs).

import {jsdoc} from 'eslint-plugin-jsdoc';

export default [
  jsdoc({
    config: 'flat/recommended',
  })
];

Or with TypeScript-aware extra rules and/or settings supplied:

import {jsdoc} from 'eslint-plugin-jsdoc';

export default [
  jsdoc({
    config: 'flat/recommended',
    rules: {
      'jsdoc/check-values': [
        'error',
        {
          allowedLicenses: [
            'MIT', 'ISC',
          ],
        },
      ],
    },
    // Uncomment this if you wish your `settings` to overwrite the config's own settings;
    //   otherwise, the default behavior is to merge recursively
    // mergeSettings: false,
    settings: {
      // Do not add a `jsdoc` child object here as you would for regular ESLint `settings`
      structuredTags: {
        see: {
          name: 'namepath-referencing',
          required: [
            'name',
          ],
        },
      },
      /*
        // Since the recommended config has been chosen, the above settings will
        //    be merged by default with the following (which are tags that are
        //    being allowed and requiring a type):
        structuredTags: {
          next: {
            required: [
              'type',
            ],
          },
        },
      */
    }
  })
];

A plugins property can also be supplied to merge with the resulting jsdoc plugin.

Other config properties such as files, ignores, etc. are also copied over, though noting that if the specified config produces an array, they will not currently function.

There is also a extraRuleDefinitions.forbid option, the details of which are explained in the Advanced docs (under creating your own rules and forbidding structures).

Flat config (declarative)

import jsdoc from 'eslint-plugin-jsdoc';

const config = [
  // configuration included in plugin
  jsdoc.configs['flat/recommended'],
  // other configuration objects...
  {
    files: ['**/*.js'],
    // `plugins` here is not necessary if including the above config
    plugins: {
      jsdoc,
    },
    rules: {
      'jsdoc/require-description': 'warn'
    }
  }
];

export default config;

The general starting rulesets you can extend from in flat config are:

• jsdoc.configs['flat/recommended']: Recommended starting rules for enforcing proper tag values, that common tags exist, and that tags are formatted and styled consistently
  • jsdoc.configs['flat/recommended-error']: The same, reporting with failing errors instead of mere warnings
• jsdoc.configs['flat/recommended-typescript']: A similar recommended starting list, adjusted for projects using TypeScript syntax (and not just the "typescript" mode setting)
  • jsdoc.configs['flat/recommended-typescript-error']: The same, reporting with failing errors instead of mere warnings
• jsdoc.configs['flat/recommended-typescript-flavor']: A similar recommended starting list, adjusted for projects using JavaScript syntax (source files that are still .js) but using TypeScript flavor within JSDoc (i.e., the default "typescript" mode in eslint-plugin-jsdoc)
  • jsdoc.configs['flat/recommended-typescript-flavor-error']: The same, reporting with failing errors instead of mere warnings

Granular Flat Configs

There also exist several more granular, standalone TypeScript rulesets you can extend from. These each only enable mostly or only rules from the recommended starting rules:

• Contents: rules that check names and descriptions
  • jsdoc.configs['flat/contents-typescript']: for TypeScript files, with reports set to warn
  • jsdoc.configs['flat/contents-typescript-error']: for TypeScript files, with reports set to error
  • jsdoc.configs['flat/contents-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
  • jsdoc.configs['flat/contents-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
• Logical: rules that enforce proper tag values
  • jsdoc.configs['flat/logical-typescript']: for TypeScript files, with reports set to warn
  • jsdoc.configs['flat/logical-typescript-error']: for TypeScript files, with reports set to error
  • jsdoc.configs['flat/logical-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
  • jsdoc.configs['flat/logical-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
• Requirements: rules that enforce tags exist or have or don't have types
  • jsdoc.configs['flat/requirements-typescript']: for TypeScript files, with reports set to warn
  • jsdoc.configs['flat/requirements-typescript-error']: for TypeScript files, with reports set to error
  • jsdoc.configs['flat/requirements-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
  • jsdoc.configs['flat/requirements-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
• Stylistic: rules that enforce clear, consistent tag formatting and styles
  • jsdoc.configs['flat/stylistic-typescript']: for TypeScript files, with reports set to warn
  • jsdoc.configs['flat/stylistic-typescript-error']: for TypeScript files, with reports set to error
  • jsdoc.configs['flat/stylistic-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
  • jsdoc.configs['flat/stylistic-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error

For example, to enforce only that any JSDoc tags and their contents are valid and styled consistently in TypeScript files, without enforcing that tags must always exist:

import jsdoc from 'eslint-plugin-jsdoc';

export default [
  jsdoc.configs['flat/contents-typescript-error'],
  jsdoc.configs['flat/logical-typescript-error'],
  jsdoc.configs['flat/stylistic-typescript-error'],
];

Why certain rules were excluded from the granular configs

A few rules were left out of the granular configs. Here is why:

Rules which might have been added to required:

• require-throws - Since this can't enforce all cases, some may not wish this rule enforced.
• require-file-overview - Too demanding for all projects
• convert-to-jsdoc-comments - Overly aggressive for some projects

Rules which might have been added to logical:

• no-missing-syntax - Has no default options.
• no-restricted-syntax - Has no default options.

Rules which might have been added to contents:

• match-name - Has no default options.
• require-description - Too demanding for all projects
• require-description-complete-sentence - Too demanding for all projects

Rules which might have been added to stylistic:

• check-indentation - May not be desired by all projects
• sort-tags - Too project-specific

eslintrc

Add plugins section to .eslintrc.* and specify eslint-plugin-jsdoc as a plugin.

{
    "plugins": [
        "jsdoc"
    ]
}

Finally, enable all of the rules that you would like to use.

{
    "rules": {
        "jsdoc/check-access": 1, // Recommended
        "jsdoc/check-alignment": 1, // Recommended
        // "jsdoc/check-examples": 1, // Deprecated and not for ESLint >= 8
        "jsdoc/check-indentation": 1,
        "jsdoc/check-line-alignment": 1,
        "jsdoc/check-param-names": 1, // Recommended
        "jsdoc/check-property-names": 1, // Recommended
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1, // Recommended
        "jsdoc/check-template-names": 1,
        "jsdoc/check-types": 1, // Recommended
        "jsdoc/check-values": 1, // Recommended
        "jsdoc/convert-to-jsdoc-comments": 1,
        "jsdoc/empty-tags": 1, // Recommended
        "jsdoc/implements-on-classes": 1, // Recommended
        "jsdoc/imports-as-dependencies": 1,
        "jsdoc/informative-docs": 1,
        "jsdoc/lines-before-block": 1,
        "jsdoc/match-description": 1,
        "jsdoc/match-name": 1,
        "jsdoc/multiline-blocks": 1, // Recommended
        "jsdoc/no-bad-blocks": 1,
        "jsdoc/no-blank-block-descriptions": 1,
        "jsdoc/no-defaults": 1, // Recommended
        "jsdoc/no-missing-syntax": 1,
        "jsdoc/no-multi-asterisks": 1, // Recommended
        "jsdoc/no-restricted-syntax": 1,
        "jsdoc/no-types": 1, // Recommended for TS configs
        "jsdoc/no-undefined-types": 1, // Recommended for non-TS configs
        "jsdoc/rejct-any-type": 1, // Recommended
        "jsdoc/reject-function-type": 1, // Recommended
        "jsdoc/require-asterisk-prefix": 1,
        "jsdoc/require-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-example": 1,
        "jsdoc/require-file-overview": 1,
        "jsdoc/require-hyphen-before-param-description": 1,
        "jsdoc/require-jsdoc": 1, // Recommended
        "jsdoc/require-next-description": 1,
        "jsdoc/require-next-type": 1, // Recommended
        "jsdoc/require-param-description": 1, // Recommended
        "jsdoc/require-param-name": 1, // Recommended
        "jsdoc/require-param-type": 1, // Recommended in non-TS configs
        "jsdoc/require-param": 1, // Recommended
        "jsdoc/require-property-description": 1, // Recommended
        "jsdoc/require-property-name": 1, // Recommended
        "jsdoc/require-property-type": 1, // Recommended in non-TS configs
        "jsdoc/require-property": 1, // Recommended
        "jsdoc/require-returns-check": 1, // Recommended
        "jsdoc/require-returns-description": 1, // Recommended
        "jsdoc/require-returns-type": 1, // Recommended in non-TS configs
        "jsdoc/require-returns": 1, // Recommended
        "jsdoc/require-template": 1,
        "jsdoc/require-throws": 1,
        "jsdoc/require-throws-description": 1,
        "jsdoc/require-throws-type": 1, // Recommended
        "jsdoc/require-yields-check": 1, // Recommended
        "jsdoc/require-yields-description": 1,
        "jsdoc/require-yields-type": 1, // Recommended
        "jsdoc/require-yields": 1, // Recommended
        "jsdoc/sort-tags": 1,
        "jsdoc/tag-lines": 1, // Recommended
        "jsdoc/text-escaping": 1,
        "jsdoc/type-formatting": 1,
        "jsdoc/valid-types": 1 // Recommended
    }
}

Or you can simply add the following to .eslintrc.*, which enables the rules commented above as "recommended":

{
  "extends": ["plugin:jsdoc/recommended"]
}

You can then selectively add to or override the recommended rules.

Alternatively, if you wish to have all linting issues reported as failing errors, you may use the "recommended-error" config:

{
  "extends": ["plugin:jsdoc/recommended-error"]
}

If you plan to use TypeScript syntax (and not just "typescript" mode to indicate the JSDoc flavor is TypeScript), you can use:

{
  "extends": ["plugin:jsdoc/recommended-typescript"]
}

...or to report with failing errors instead of mere warnings:

{
  "extends": ["plugin:jsdoc/recommended-typescript-error"]
}

If you are not using TypeScript syntax (your source files are still .js files) but you are using the TypeScript flavor within JSDoc (i.e., the default "typescript" mode in eslint-plugin-jsdoc) and you are perhaps using allowJs and checkJs options of TypeScript's tsconfig.json), you may use:

{
  "extends": ["plugin:jsdoc/recommended-typescript-flavor"]
}

...or to report with failing errors instead of mere warnings:

{
  "extends": ["plugin:jsdoc/recommended-typescript-flavor-error"]
}

Options

Rules may, as per the ESLint user guide, have their own individual options. In eslint-plugin-jsdoc, a few options, such as, exemptedBy and contexts, may be used across different rules.

eslint-plugin-jsdoc options, if present, are generally in the form of an object supplied as the second argument in an array after the error level (any exceptions to this format are explained within that rule's docs).

// `.eslintrc.js`
{
  rules: {
    'jsdoc/require-example': [
        // The Error level should be `error`, `warn`, or `off` (or 2, 1, or 0)
        'error',
        // The options vary by rule, but are generally added to an options
        //  object as follows:
        {
          checkConstructors: true,
          exemptedBy: ['type']
        }
    ]
  }
}

Settings

See Settings.

Advanced

See Advanced.

Processors

See our @example and other item processors.

Rules

Problems reported by rules which have a wrench 🔧 below can be fixed automatically by running ESLint on the command line with --fix option.

Note that a number of fixable rules have an enableFixer option which can be set to false to disable the fixer (or in the case of check-param-names, check-property-names, and no-blank-blocks, set to true to enable a non-default-recommended fixer).

recommended	fixable	rule	description
✔️		check-access	Checks that @access tags have a valid value.
✔️	🔧	check-alignment	Reports invalid alignment of JSDoc block asterisks.
		check-examples	@deprecated - Use getJsdocProcessorPlugin processor; ensures that (JavaScript) samples within @example tags adhere to ESLint rules.
		check-indentation	Reports invalid padding inside JSDoc blocks.
	🔧	check-line-alignment	Reports invalid alignment of JSDoc block lines.
✔️	🔧	check-param-names	Checks for dupe @param names, that nested param names have roots, and that parameter names in function declarations match JSDoc param names.
✔️	🔧	check-property-names	Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots.
		check-syntax	Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode).
✔️	🔧	check-tag-names	Reports invalid block tag names.
		check-template-names	Checks that any @template names are actually used in the connected @typedef or type alias.
✔️	🔧	check-types	Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements).
✔️		check-values	This rule checks the values for a handful of tags: @version, @since, @license and @author.
	🔧	convert-to-jsdoc-comments	Converts non-JSDoc comments preceding or following nodes into JSDoc ones
✔️	🔧	empty-tags	Checks tags that are expected to be empty (e.g., @abstract or @async), reporting if they have content
✔️		implements-on-classes	Prohibits use of @implements on non-constructor functions (to enforce the tag only being used on classes/constructors).
		imports-as-dependencies	Reports if JSDoc import() statements point to a package which is not listed in dependencies or devDependencies
		informative-docs	This rule reports doc comments that only restate their attached name.
	🔧	lines-before-block	Enforces minimum number of newlines before JSDoc comment blocks
		match-description	Enforces a regular expression pattern on descriptions.
	🔧	match-name	Reports the name portion of a JSDoc tag if matching or not matching a given regular expression.
✔️	🔧	multiline-blocks	Controls how and whether JSDoc blocks can be expressed as single or multiple line blocks.
	🔧	no-bad-blocks	This rule checks for multi-line-style comments which fail to meet the criteria of a JSDoc block.
	🔧	no-blank-block-descriptions	If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description.
	🔧	no-blank-blocks	Removes empty blocks with nothing but possibly line breaks
✔️	🔧	no-defaults	This rule reports defaults being used on the relevant portion of @param or @default.
		no-missing-syntax	Reports when certain comment structures are always expected.
✔️	🔧	no-multi-asterisks	Prevents use of multiple asterisks at the beginning of lines.
		no-restricted-syntax	Reports when certain comment structures are present.
On in TS; Off in TS flavor	🔧	no-types	This rule reports types being used on @param or @returns (redundant with TypeScript).
✔️ (Off in TS; Off in TS flavor)		no-undefined-types	Besides some expected built-in types, prohibits any types not specified as globals or within @typedef.
✔️		reject-any-type	Reports use of any or * type
✔️		reject-function-type	Reports use of Function type
	🔧	require-asterisk-prefix	Requires that each JSDoc line starts with an *.
		require-description	Requires that all functions (and potentially other contexts) have a description.
	🔧	require-description-complete-sentence	Requires that block description, explicit @description, and @param/@returns tag descriptions are written in complete sentences.
	🔧	require-example	Requires that all functions (and potentially other contexts) have examples.
		require-file-overview	Checks that all files have one @file, @fileoverview, or @overview tag at the beginning of the file.
	🔧	require-hyphen-before-param-description	Requires a hyphen before the @param description (and optionally before @property descriptions).
✔️	🔧	require-jsdoc	Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports).
		require-next-description	Requires a description for @next tags
✔️		require-next-type	Requires a type for @next tags
✔️	🔧	require-param	Requires that all function parameters are documented with a @param tag.
✔️	🔧	require-param-description	Requires that each @param tag has a description value.
✔️		require-param-name	Requires that all @param tags have names.
✔️ (Off in TS; On in TS flavor)	🔧	require-param-type	Requires that each @param tag has a type value (in curly brackets).
✔️	🔧	require-property	Requires that all @typedef and @namespace tags have @property when their type is a plain object, Object, or PlainObject.
✔️		require-property-description	Requires that each @property tag has a description value.
✔️		require-property-name	Requires that all @property tags have names.
✔️ (Off in TS; On in TS flavor)		require-property-type	Requires that each @property tag has a type value (in curly brackets).
✔️	🔧	require-returns	Requires that returns are documented with @returns.
✔️		require-returns-check	Requires a return statement in function body if a @returns tag is specified in JSDoc comment(and reports if multiple @returns tags are present).
✔️		require-returns-description	Requires that the @returns tag has a description value (not including void/undefined type returns).
✔️ (Off in TS; On in TS flavor)		require-returns-type	Requires that @returns tag has type value (in curly brackets).
		require-template	Requires @template tags be present when type parameters are used.
		require-throws	Requires that throw statements are documented with @throws tags.
		require-throws-description	Requires a description for @throws tags
✔️		require-throws-type	Requires a type for @throws tags
✔️		require-yields	Requires yields are documented with @yields tags.
✔️		require-yields-check	Ensures that if a @yields is present that a yield (or yield with a value) is present in the function body (or that if a @next is present that there is a yield with a return value present).
		require-yields-description	Requires a description for @yields tags
✔️		require-yields-type	Requires a type for @yields tags
	🔧	sort-tags	Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups.
✔️	🔧	tag-lines	Enforces lines (or no lines) between tags.
	🔧	text-escaping	Auto-escape certain characters that are input within block and tag descriptions.
	🔧	type-formatting	Formats JSDoc type values.
✔️		valid-types	Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings).