eslint-plugin-jsdoc
v50.2.2
Published
JSDoc linting rules for ESLint.
Downloads
9,000,077
Readme
eslint-plugin-jsdoc
JSDoc linting rules for ESLint.
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;
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 consistentlyjsdoc.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
ineslint-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 warnjsdoc.configs['flat/contents-typescript-error']
: for TypeScript files, with reports set to errorjsdoc.configs['flat/contents-typescript-flavor']
: for files using JavaScript syntax and JSDoc types, with reports set to warnjsdoc.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 warnjsdoc.configs['flat/logical-typescript-error']
: for TypeScript files, with reports set to errorjsdoc.configs['flat/logical-typescript-flavor']
: for files using JavaScript syntax and JSDoc types, with reports set to warnjsdoc.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
jsdoc.configs['flat/requirements-typescript']
: for TypeScript files, with reports set to warnjsdoc.configs['flat/requirements-typescript-error']
: for TypeScript files, with reports set to errorjsdoc.configs['flat/requirements-typescript-flavor']
: for files using JavaScript syntax and JSDoc types, with reports set to warnjsdoc.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 warnjsdoc.configs['flat/stylistic-typescript-error']
: for TypeScript files, with reports set to errorjsdoc.configs['flat/stylistic-typescript-flavor']
: for files using JavaScript syntax and JSDoc types, with reports set to warnjsdoc.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 projectsconvert-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 projectsrequire-description-complete-sentence
- Too demanding for all projects
Rules which might have been added to stylistic
:
check-indentation
- May not be desired by all projectssort-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,
"jsdoc/check-indentation": 1,
"jsdoc/check-line-alignment": 1,
"jsdoc/check-param-names": 1, // Recommended
"jsdoc/check-template-names": 1,
"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-template": 1,
"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.
Processors
See our @example
and other item processors.
Rules
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).
|recommended|fixable|rule|description|
|-|-|-|-|
|:heavy_check_mark:|| check-access | Enforces valid @access
tags|
|:heavy_check_mark:|:wrench:| check-alignment|Enforces alignment of JSDoc block asterisks|
|||check-examples|Linting of JavaScript within @example
|
|||check-indentation|Checks for invalid padding inside JSDoc blocks|
||:wrench:|check-line-alignment|Reports invalid alignment of JSDoc block lines.|
|:heavy_check_mark:|:wrench:|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.|
|:heavy_check_mark:|:wrench:|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)|
|:heavy_check_mark:|:wrench:|check-tag-names|Reports invalid jsdoc (block) tag names|
| || check-template-names|Checks that any @template
names are actually used in the connected @typedef
or type alias.
|:heavy_check_mark:|:wrench:|check-types|Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements)|
|:heavy_check_mark:||check-values|Checks for expected content within some miscellaneous tags (@version
, @since
, @license
, @author
)|
| || convert-to-jsdoc-comments | Converts line and block comments preceding or following specified nodes into JSDoc comments|
|:heavy_check_mark:|:wrench:|empty-tags|Checks tags that are expected to be empty (e.g., @abstract
or @async
), reporting if they have content|
|:heavy_check_mark:||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 restate their attached name.|
|||lines-before-block|Enforces minimum number of newlines before JSDoc comment blocks|
|||match-description|Defines customizable regular expression rules for your tag descriptions|
||:wrench:|match-name|Reports the name portion of a JSDoc tag if matching or not matching a given regular expression|
|:heavy_check_mark:|:wrench:|multiline-blocks|Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks|
||:wrench:|no-bad-blocks|This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block|
||:wrench:|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.|
||:wrench:|no-blank-blocks|Reports and optionally removes blocks with whitespace only|
|:heavy_check_mark:|:wrench:|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.|
|:heavy_check_mark:|:wrench:|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|:wrench:|no-types|Prohibits types on @param
or @returns
(redundant with TypeScript)|
|:heavy_check_mark: (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
|
||:wrench:|require-asterisk-prefix|Requires that each JSDoc line starts with an *
|
|||require-description|Requires that all functions (and potentially other contexts) have a description.|
||:wrench:|require-description-complete-sentence|Requires that block description, explicit @description
, and @param
/@returns
tag descriptions are written in complete sentences|
||:wrench:|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|
||:wrench:|require-hyphen-before-param-description|Requires a hyphen before @param
descriptions (and optionally before @property
descriptions)|
|:heavy_check_mark:|:wrench:|require-jsdoc|Checks for presence of jsdoc comments, on functions and potentially other contexts (optionally limited to exports).|
|:heavy_check_mark:|:wrench:|require-param|Requires that all function parameters are documented with a @param
tag.|
|:heavy_check_mark:||require-param-description|Requires that each @param
tag has a description
value.|
|:heavy_check_mark:||require-param-name|Requires that all @param
tags have names.|
|:heavy_check_mark: (off in TS)||require-param-type|Requires that each @param
tag has a type value (within curly brackets).|
|:heavy_check_mark:|:wrench:|require-property|Requires that all @typedef
and @namespace
tags have @property
tags when their type is a plain object
, Object
, or PlainObject
.|
|:heavy_check_mark:||require-property-description|Requires that each @property
tag has a description
value.|
|:heavy_check_mark:||require-property-name|Requires that all @property
tags have names.|
|:heavy_check_mark: (off in TS)||require-property-type|Requires that each @property
tag has a type value (within curly brackets).|
|:heavy_check_mark:||require-returns|Requires that return statements are documented.|
|:heavy_check_mark:||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).|
|:heavy_check_mark:||require-returns-description|Requires that the @returns
tag has a description
value (not including void
/undefined
type returns).|
|:heavy_check_mark: (off in TS)||require-returns-type|Requires that @returns
tag has a 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|
|:heavy_check_mark:||require-yields|Requires that yields are documented|
|:heavy_check_mark:||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|
|:heavy_check_mark:|:wrench:|tag-lines|Enforces lines (or no lines) between tags|
||:wrench:|text-escaping|This rule can auto-escape certain characters that are input within block and tag descriptions|
|:heavy_check_mark:||valid-types|Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings)|