README
eslint-plugin-jsdoc
JSDoc linting rules for ESLint.
- eslint-plugin-jsdoc
- Installation
- Configuration
- Options
- Settings
- Allow tags (
@private
or@internal
) to disable rules for that comment block maxLines
andminLines
- Mode
- Alias Preference
@override
/@augments
/@extends
/@implements
/@ignore
Without Accompanying@param
/@description
/@example
/@returns
/@throws
/@yields
- Settings to Configure
check-types
andno-undefined-types
structuredTags
- Allow tags (
- Advanced
- Rules
check-access
check-alignment
check-examples
check-indentation
check-line-alignment
check-param-names
check-property-names
check-syntax
check-tag-names
check-types
check-values
empty-tags
implements-on-classes
match-description
match-name
multiline-blocks
newline-after-description
no-bad-blocks
no-defaults
no-missing-syntax
no-multi-asterisks
no-restricted-syntax
no-types
no-undefined-types
require-asterisk-prefix
require-description-complete-sentence
require-description
require-example
require-file-overview
require-hyphen-before-param-description
require-jsdoc
require-param-description
require-param-name
require-param-type
require-param
require-property
require-property-description
require-property-name
require-property-type
require-returns-check
require-returns-description
require-returns-type
require-returns
require-throws
require-yields
require-yields-check
sort-tags
tag-lines
valid-types
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
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/match-description": 1,
"jsdoc/multiline-blocks": 1, // Recommended
"jsdoc/newline-after-description": 1, // Recommended
"jsdoc/no-bad-blocks": 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/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.
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:
{
avoidExampleOnConstructors: true,
exemptedBy: ['type']
}
]
}
}
Settings
@private
or @internal
) to disable rules for that comment block
Allow tags (settings.jsdoc.ignorePrivate
- Disables all rules for the comment block on which a@private
tag (or@access private
) occurs. Defaults tofalse
. Note: This has no effect with the rulecheck-access
(whose purpose is to check access modifiers) orempty-tags
(which checks@private
itself).settings.jsdoc.ignoreInternal
- Disables all rules for the comment block on which a@internal
tag occurs. Defaults tofalse
. Note: This has no effect with the ruleempty-tags
(which checks@internal
itself).
maxLines
and minLines
One can use minLines
and maxLines
to indicate how many line breaks
(if any) will be checked to find a jsdoc comment block before the given
code block. These settings default to 0
and 1
respectively.
In conjunction with the require-jsdoc
rule, these settings can
be enforced so as to report problems if a jsdoc block is not found within
the specified boundaries. The settings are also used in the fixer to determine
how many line breaks to add when a block is missing.
Mode
settings.jsdoc.mode
- Set totypescript
,closure
, orjsdoc
(the default unless the@typescript-eslint
parser is in use in which casetypescript
will be the default). Note that if you do not wish to use separate.eslintrc.*
files for a project containing both JavaScript and TypeScript, you can also useoverrides
. You may also set to"permissive"
to try to be as accommodating to any of the styles, but this is not recommended. Currently is used for the following:check-tag-names
: Determine valid tags and aliasesno-undefined-types
: Only check@template
for types in "closure" and "typescript" modescheck-syntax
: determines aspects that may be enforcedvalid-types
: in non-Closure mode,@extends
,@package
and access tags (e.g.,@private
) with a bracketed type are reported as are missing names with@typedef
- For type/namepath-checking rules, determine which tags will be checked for types/namepaths (Closure allows types on some tags which the others do not, so these tags will additionally be checked in "closure" mode)
- For type-checking rules, impacts parsing of types (through jsdoc-type-pratt-parser dependency)
- Check preferred tag names
- Disallows namepath on
@interface
for "closure" mode invalid-types
(and avoids checking in other rules)
Alias Preference
Use settings.jsdoc.tagNamePreference
to configure a preferred alias name for
a JSDoc tag. The format of the configuration is:
<primary tag name>: <preferred alias name>
, e.g.
{
"rules": {},
"settings": {
"jsdoc": {
"tagNamePreference": {
"param": "arg",
"returns": "return"
}
}
}
}
Note: ESLint does not allow settings to have keys which conflict with
Object.prototype
e.g. 'constructor'
. To work around this, you can use the
key 'tag constructor'
.
One may also use an object with a message
and replacement
.
The following will report the message
@extends is to be used over @augments as it is more evocative of classes than @augments
upon encountering @augments
.
{
"rules": {},
"settings": {
"jsdoc": {
"tagNamePreference": {
"augments": {
"message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
"replacement": "extends"
}
}
}
}
}
If one wishes to reject a normally valid tag, e.g., @todo
, one may set the
tag to false
:
{
"rules": {},
"settings": {
"jsdoc": {
"tagNamePreference": {
"todo": false
}
}
}
}
A project wishing to ensure no blocks are left excluded from entering the
documentation, might wish to prevent the @ignore
tag in the above manner.
Or one may set the targeted tag to an object with a custom message
, but
without a replacement
property:
{
"rules": {},
"settings": {
"jsdoc": {
"tagNamePreference": {
"todo": {
"message": "We expect immediate perfection, so don't leave to-dos in your code."
}
}
}
}
}
Note that the preferred tags indicated in the
settings.jsdoc.tagNamePreference
map will be assumed to be defined by
check-tag-names
.
See check-tag-names
for how that fact can be used to set an alias to itself
to allow both the alias and the default (since aliases are otherwise not
permitted unless used in tagNamePreference
).
Default Preferred Aliases
The defaults in eslint-plugin-jsdoc
(for tags which offer
aliases) are as follows:
@abstract
(over@virtual
)@augments
(over@extends
)@class
(over@constructor
)@constant
(over@const
)@default
(over@defaultvalue
)@description
(over@desc
)@external
(over@host
)@file
(over@fileoverview
,@overview
)@fires
(over@emits
)@function
(over@func
,@method
)@member
(over@var
)@param
(over@arg
,@argument
)@property
(over@prop
)@returns
(over@return
)@throws
(over@exception
)@yields
(over@yield
)
This setting is utilized by the the rule for tag name checking
(check-tag-names
) as well as in the @param
and @require
rules:
check-param-names
check-tag-names
require-hyphen-before-param-description
require-description
require-param
require-param-description
require-param-name
require-param-type
require-returns
require-returns-check
require-returns-description
require-returns-type
@override
/@augments
/@extends
/@implements
/@ignore
Without Accompanying @param
/@description
/@example
/@returns
/@throws
/@yields
The following settings allows the element(s) they reference to be omitted
on the JSDoc comment block of the function or that of its parent class
for any of the "require" rules (i.e., require-param
, require-description
,
require-example
, require-returns
, require-throws
, require-yields
).
settings.jsdoc.ignoreReplacesDocs
(@ignore
) - Defaults totrue
settings.jsdoc.overrideReplacesDocs
(@override
) - Defaults totrue
settings.jsdoc.augmentsExtendsReplacesDocs
(@augments
or its alias@extends
) - Defaults tofalse
.settings.jsdoc.implementsReplacesDocs
(@implements
) - Defaults tofalse
The format of the configuration is as follows:
{
"rules": {},
"settings": {
"jsdoc": {
"ignoreReplacesDocs": true,
"overrideReplacesDocs": true,
"augmentsExtendsReplacesDocs": true,
"implementsReplacesDocs": true
}
}
}
check-types
and no-undefined-types
Settings to Configure settings.jsdoc.preferredTypes
An option map to indicate preferred or forbidden types (if default types are indicated here, these will have precedence over the default recommendations forcheck-types
). The keys of this map are the types to be replaced (or forbidden). These keys may include:- The "ANY" type,
*
- The pseudo-type
[]
which we use to denote the parent (array) types used in the syntaxstring[]
,number[]
, etc. - The pseudo-type
.<>
(or.
) to represent the formatArray.<value>
orObject.<key, value>
- The pseudo-type
<>
to represent the formatArray<value>
orObject<key, value>
- A plain string type, e.g.,
MyType
- A plain string type followed by one of the above pseudo-types (except
for
[]
which is always assumed to be anArray
), e.g.,Array.
, orSpecialObject<>
.
If a bare pseudo-type is used, it will match all parent types of that form. If a pseudo-type prefixed with a type name is used, it will only match parent types of that form and type name.
The values can be:
false
to forbid the type- a string to indicate the type that should be preferred in its place
(and which
fix
mode can replace); this can be one of the formats of the keys described above.- Note that the format will not be changed unless you use a pseudo-type
in the replacement. (For example,
'Array.<>': 'MyArray'
will changeArray.<string>
toMyArray.<string>
, preserving the dot. To get rid of the dot, you must use the pseudo-type with<>
, i.e.,'Array.<>': 'MyArray<>'
, which will changeArray.<string>
toMyArray<string>
). - If you use a bare pseudo-type in the replacement (e.g.,
'MyArray.<>': '<>'
), the type will be converted to the format of the pseudo-type without changing the type name. For example,MyArray.<string>
will becomeMyArray<string>
butArray.<string>
will not be modified.
- Note that the format will not be changed unless you use a pseudo-type
in the replacement. (For example,
- an object with:
- the key
message
to provide a specific error message when encountering the discouraged type.- The message string will have the substrings with special meaning,
{{tagName}}
and{{tagValue}}
, replaced with their corresponding value.
- The message string will have the substrings with special meaning,
- an optional key
replacement
with either of the following values:- a string type to be preferred in its place (and which
fix
mode can replace) false
(for forbidding the type)
- a string type to be preferred in its place (and which
- the key
- The "ANY" type,
Note that the preferred types indicated as targets in
settings.jsdoc.preferredTypes
map will be assumed to be defined by
no-undefined-types
.
See the option of check-types
, unifyParentAndChildTypeChecks
, for
how the keys of preferredTypes
may have <>
or .<>
(or just .
)
appended and its bearing on whether types are checked as parents/children
only (e.g., to match Array
if the type is Array
vs. Array.<string>
).
Note that if a value is present both as a key and as a value, neither the
key nor the value will be reported. Thus in check-types
, this fact can
be used to allow both object
and Object
if one has a preferredTypes
key object: 'Object'
and Object: 'object'
.
structuredTags
An object indicating tags whose types and names/namepaths (whether defining or
referencing namepaths) will be checked, subject to configuration. If the tags
have predefined behavior or allowEmptyNamepaths
behavior, this option will
override that behavior for any specified tags, though this option can also be
used for tags without predefined behavior. Its keys are tag names and its
values are objects with the following optional properties:
name
- String set to one of the following:"text"
- When a name is present, plain text will be allowed in the name position (non-whitespace immediately after the tag and whitespace), e.g., in@throws This is an error
, "This" would normally be the name, but "text" allows non-name text here also. This is the default."namepath-defining"
- As withnamepath-referencing
, but also indicates the tag adds a namepath to definitions, e.g., to preventno-undefined-types
from reporting references to that namepath."namepath-referencing"
- This will cause any name position to be checked to ensure it is a valid namepath. You might use this to ensure that tags which normally allow free text, e.g.,@see
will instead require a namepath.false
- This will disallow any text in the name position.
type
:true
- Allows valid types within brackets. This is the default.false
- Explicitly disallows any brackets or bracketed type. You might use this with@throws
to suggest that only free form text is being input or with@augments
(for jsdoc mode) to disallow Closure-style bracketed usage along with a required namepath.- (An array of strings) - A list of permissible types.
required
- Array of one of the following (defaults to an empty array, meaning none are required):- One or both of the following strings (if both are included, then both
are required):
"name"
- Indicates that a name position is required (not just that if present, it is a valid namepath). You might use this withsee
to insist that a value (or namepath, depending on thename
value) is always present."type"
- Indicates that the type position (within curly brackets) is required (not just that if present, it is a valid type). You might use this with@throws
or@typedef
which might otherwise normally have their types optional. See the type groups 3-5 above.
"typeOrName"
- Must have either type (e.g.,@throws {aType}
) or name (@throws Some text
); does not require that both exist but disallows just an empty tag.
- One or both of the following strings (if both are included, then both
are required):
Advanced
AST and Selectors
For various rules, one can add to the environments to which the rule applies
by using the contexts
option.
This option works with ESLint's selectors which are esquery expressions one may use to target a specific node type or types, including subsets of the type(s) such as nodes with certain children or attributes.
These expressions are used within ESLint plugins to find those parts of
your files' code which are of interest to check. However, in
eslint-plugin-jsdoc
, we also allow you to use these selectors to define
additional contexts where you wish our own rules to be applied.
contexts
format
While at their simplest, these can be an array of string selectors, one can
also supply an object with context
(in place of the string) and one of two
properties:
- For
require-jsdoc
, there is also ainlineCommentBlock
property. See that rule for details. - For
no-missing-syntax
andno-restricted-syntax
, there is also amessage
property which allows customization of the message to be shown when the rule is triggered. - For
no-missing-syntax
, there is also aminimum
property. See that rule. - For other rules, there is a
comment
property which adds to thecontext
in requiring that thecomment
AST condition is also met, e.g., to require that certain tags are present and/or or types and type operators are in use. Note that this AST (either forJsdoc*
orJsdocType*
AST) has not been standardized and should be considered experimental. Note that this property might also become obsolete if parsers begin to include JSDoc-structured AST. A parser is available which aims to support comment AST as a first class citizen where comment/comment types can be used anywhere within a normal AST selector but this should only be considered experimental. When using such a parser, you need not usecomment
and can just use a plain string context. The determination of the node on which the comment is attached is also subject to change. It may be currently possible for different structures to map to the same comment block. This is because normally when querying to find either the declaration of the function expression forconst quux = function () {}
, the associated comment would, in both cases, generally be expected to be on the line above both, rather than to be immediately preceding the function (in the case of the function). See @es-joy/jsdoccomment for the precise structure of the comment (and comment type) nodes.
Discovering available AST definitions
To know all of the AST definitions one may target, it will depend on the
parser
you are using with ESLint (e.g., espree
is the default parser for ESLint,
and this follows EStree AST but
to support the the latest experimental features of JavaScript, one may use
@babel/eslint-parser
or to be able to have one's rules (including JSDoc rules)
apply to TypeScript, one may use @typescript-eslint/parser
, etc.
So you can look up a particular parser to see its rules, e.g., browse through the ESTree docs as used by Espree or see ESLint's overview of the structure of AST.
However, it can sometimes be even more helpful to get an idea of AST by just providing some of your JavaScript to the wonderful AST Explorer tool and see what AST is built out of your code. You can set the tool to the specific parser which you are using.
Uses/Tips for AST
And if you wish to introspect on the AST of code within your projects, you can use eslint-plugin-query. Though it also works as a plugin, you can use it with its own CLI, e.g., to search your files for matching esquery selectors, optionally showing it as AST JSON.
Tip: If you want to more deeply understand not just the resulting AST tree
structures for any given code but also the syntax for esquery selectors so
that you can, for example, find only those nodes with a child of a certain
type, you can set the "Transform" feature to ESLint and test out
esquery selectors in place of the selector expression (e.g., replace
'VariableDeclaration > VariableDeclarator > Identifier[name="someVar"]'
as
we have
here)
to the selector you wish so as to get messages reported in the bottom right
pane which match your esquery
selector).
Rules
check-access
Checks that @access
tags use one of the following values:
- "package", "private", "protected", "public"
Also reports:
- Mixing of
@access
with@public
,@private
,@protected
, or@package
on the same doc block. - Use of multiple instances of
@access
(or the@public
, etc. style tags) on the same doc block.
Context | everywhere |
Tags | @access |
Recommended | false |
Settings | |
Options |
The following patterns are considered problems:
/**
* @access foo
*/
function quux (foo) {
}
// Message: Missing valid JSDoc @access level.
/**
* @access foo
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
// Message: Missing valid JSDoc @access level.
/**
* @accessLevel foo
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}}
// Message: Missing valid JSDoc @accessLevel level.
/**
* @access
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"access":false}}}
// Message: Unexpected tag `@access`
class MyClass {
/**
* @access
*/
myClassField = 1
}
// Message: Missing valid JSDoc @access level.
/**
* @access public
* @public
*/
function quux (foo) {
}
// Message: The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public).
/**
* @access public
* @access private
*/
function quux (foo) {
}
// Message: At most one access-control tag may be present on a jsdoc block.
/**
* @access public
* @access private
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
// Message: At most one access-control tag may be present on a jsdoc block.
/**
* @public
* @private
*/
function quux (foo) {
}
// Message: At most one access-control tag may be present on a jsdoc block.
/**
* @public
* @private
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
// Message: At most one access-control tag may be present on a jsdoc block.
/**
* @public
* @public
*/
function quux (foo) {
}
// Message: At most one access-control tag may be present on a jsdoc block.
The following patterns are not considered problems:
/**
*
*/
function quux (foo) {
}
/**
* @access public
*/
function quux (foo) {
}
/**
* @accessLevel package
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}}
class MyClass {
/**
* @access private
*/
myClassField = 1
}
/**
* @public
*/
function quux (foo) {
}
/**
* @private
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
check-alignment
Reports invalid alignment of JSDoc block asterisks.
Context | everywhere |
Tags | N/A |
Recommended | true |
The following patterns are considered problems:
/**
* @param {Number} foo
*/
function quux (foo) {
// with spaces
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
// with tabs
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
// with spaces
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
// with spaces
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
}
// Message: Expected JSDoc block to be aligned.
/**
* @param {Number} foo
*/
function quux (foo) {
}
// Message: Expected JSDoc block to be aligned.
/**
* A jsdoc not attached to any node.
*/
// Message: Expected JSDoc block to be aligned.
class Foo {
/**
* Some method
* @param a
*/
quux(a) {}
}
// Message: Expected JSDoc block to be aligned.
The following patterns are not considered problems:
/**
* Desc
*
* @param {Number} foo
*/
function quux (foo) {
}
/**
* Desc
*
* @param {{
foo: Bar,
bar: Baz
* }} foo
*
*/
function quux (foo) {
}
/* <- JSDoc must start with 2 stars.
* So this is unchecked.
*/
function quux (foo) {}
/**
* @param {Number} foo
* @private
*/
function quux (foo) {
// with spaces
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
/**
* @param {Number} foo
* @access private
*/
function quux (foo) {
// with spaces
}
// Settings: {"jsdoc":{"ignorePrivate":true}}
check-examples
NOTE: This rule currently does not work in ESLint 8 (we are waiting for issue 14745).
Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
has options to lint the default values of optional @param
/@arg
/@argument
and @property
/@prop
tags or the values of @default
/@defaultvalue
tags.
Options
The options below all default to no-op/false
except as noted.
captionRequired
JSDoc specs use of an optional <caption>
element at the beginning of
@example
.
The option captionRequired
insists on a <caption>
being present at
the beginning of any @example
.
Used only for @example
.
exampleCodeRegex
and rejectExampleCodeRegex
JSDoc does not specify a formal means for delimiting code blocks within
@example
(it uses generic syntax highlighting techniques for its own
syntax highlighting). The following options determine whether a given
@example
tag will have the check-examples
checks applied to it:
exampleCodeRegex
- Regex which whitelists lintable examples. If a parenthetical group is used, the first one will be used, so you may wish to use(?:...)
groups where you do not wish the first such group treated as one to include. If no parenthetical group exists or matches, the whole matching expression will be used. An example might be"^```(?:js|javascript)([\\s\\S]*)```\s*