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: [
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;
If you are using defineConfig, you can build as follows:
import jsdoc from 'eslint-plugin-jsdoc';import {defineConfig} from 'eslint/config';export default defineConfig([ { name: 'jsdoc-js', // Useful with `eslint --inspect-config` files: ['**/*.{js,mjs,cjs}'], plugins: { jsdoc }, rules: { ...jsdoc.configs['flat/recommended'].rules } }]);
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
jsdoc.configs['flat/recommended-tsdoc']: Like flat/recommended-typescript but with require-throws-type, require-yields-type, and require-next-type turned off, for use with TSDoc (e.g., TypeDoc)
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
: for TypeScript files, 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.
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:
If you are using TSDoc (e.g., with TSDoc or
TypeDoc), you may use the tsdoc config, which is like
recommended-typescript but additionally turns off require-throws-type,
require-yields-type, and require-next-type (since TSDoc does not support
{Type} annotations on those tags):
{ "extends": ["plugin:jsdoc/recommended-tsdoc"]}
...or to report with failing errors instead of mere warnings:
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'] } ] }}
Problems reported by rules which have a wrench :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).
// 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',
],
},
rejects: {
required: [
'type',
],
},
},
*/
}
})
];
jsdoc.configs['flat/recommended-tsdoc-error']: The same, reporting with failing errors instead of mere warnings
jsdoc.configs['flat/recommended-mixed']: A combination of flat/recommended-typescript-flavor and flat/recommended-typescript with automatic assignment of subconfig based on file extension (**/*.{js,jsx,cjs,mjs} and **/*.{ts,tsx,cts,mts}, respectively)
jsdoc.configs['flat/stylistic-typescript-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
"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
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.
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).