eslint-plugin-jsdoc

JSDoc linting rules for ESLint.

eslint-plugin-jsdoc
- Installation
- Configuration
  - Flat config
  - eslintrc
- Options
- Settings
- Advanced
- 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

import jsdoc from 'eslint-plugin-jsdoc';

const config = [
  // configuration included in plugin
  jsdoc.configs['flat/recommended'],
  // other configuration objects...
  {
    files: ['**/*.js'],
    plugins: {
      jsdoc,
    },
    rules: {
      'jsdoc/require-description': 'warn'
    }
  }
];

export default config;

`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,
        "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-types": 1, // Recommended
        "jsdoc/check-values": 1, // Recommended
        "jsdoc/empty-tags": 1, // Recommended
        "jsdoc/implements-on-classes": 1, // Recommended
        "jsdoc/informative-docs": 1,
        "jsdoc/match-description": 1,
        "jsdoc/multiline-blocks": 1, // Recommended
        "jsdoc/no-bad-blocks": 1,
        "jsdoc/no-blank-block-descriptions": 1,
        "jsdoc/no-defaults": 1,
        "jsdoc/no-missing-syntax": 1,
        "jsdoc/no-multi-asterisks": 1, // Recommended
        "jsdoc/no-restricted-syntax": 1,
        "jsdoc/no-types": 1,
        "jsdoc/no-undefined-types": 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-param": 1, // Recommended
        "jsdoc/require-param-description": 1, // Recommended
        "jsdoc/require-param-name": 1, // Recommended
        "jsdoc/require-param-type": 1, // Recommended
        "jsdoc/require-property": 1, // Recommended
        "jsdoc/require-property-description": 1, // Recommended
        "jsdoc/require-property-name": 1, // Recommended
        "jsdoc/require-property-type": 1, // Recommended
        "jsdoc/require-returns": 1, // Recommended
        "jsdoc/require-returns-check": 1, // Recommended
        "jsdoc/require-returns-description": 1, // Recommended
        "jsdoc/require-returns-type": 1, // Recommended
        "jsdoc/require-throws": 1,
        "jsdoc/require-yields": 1, // Recommended
        "jsdoc/require-yields-check": 1, // Recommended
        "jsdoc/sort-tags": 1,
        "jsdoc/tag-lines": 1, // Recommended
        "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.

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	Enforces valid `@access` tags
✔️	🔧	check-alignment	Enforces alignment of JSDoc block asterisks
		check-examples	Linting of JavaScript within `@example`
		check-indentation	Checks for 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	Checks for dupe `@property` names, that nested property names have roots
		check-syntax	Reports use against current mode (currently only prohibits Closure-specific syntax)
✔️	🔧	check-tag-names	Reports invalid jsdoc (block) tag names
✔️	🔧	check-types	Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements)
✔️		check-values	Checks for expected content within some miscellaneous tags (`@version`, `@since`, `@license`, `@author`)
✔️	🔧	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)
		informative-docs	Reports on JSDoc texts that serve only to restart their attached name.
		match-description	Defines customizable regular expression rules for your tag 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	Reports and optionally removes blocks with whitespace only
✔️	🔧	no-defaults	This rule reports defaults being used on the relevant portion of `@param` or `@default`
		no-missing-syntax	This rule lets you report if certain always expected comment structures are missing.
✔️	🔧	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	🔧	no-types	Prohibits types on `@param` or `@returns` (redundant with TypeScript)
✔️ (off in TS and TS flavor)		no-undefined-types	Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`
	🔧	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	By default, requires a single `@file` tag at the beginning of each linted file
	🔧	require-hyphen-before-param-description	Requires a hyphen before `@param` descriptions (and optionally before `@property` descriptions)
✔️	🔧	require-jsdoc	Checks for presence of jsdoc comments, on functions and potentially other contexts (optionally limited to exports).
✔️	🔧	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)		require-param-type	Requires that each `@param` tag has a type value (within curly brackets).
✔️	🔧	require-property	Requires that all `@typedef` and `@namespace` tags have `@property` tags 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)		require-property-type	Requires that each `@property` tag has a type value (within curly brackets).
✔️		require-returns	Requires that return statements are documented.
✔️		require-returns-check	Requires a return statement be present in a function body if a `@returns` tag is specified in the jsdoc comment block (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)		require-returns-type	Requires that `@returns` tag has a type value (in curly brackets).
		require-throws	Requires that throw statements are documented
✔️		require-yields	Requires that yields are documented
✔️		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)
		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	This rule can auto-escape certain characters that are input within block and tag descriptions
✔️		valid-types	Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings)

gajus/eslint-plugin-jsdoc

gajus

Reviews

Repository Details