eslint-plugin-jsdoc
JSDoc linting rules for ESLint.
- eslint-plugin-jsdoc
- Reference to jscs-jsdoc
- Installation
- Configuration
- Settings
- Allow
@private
to disable rules for that comment block - Exempting empty functions from
require-jsdoc
- Alias Preference
- Additional Tag Names
@override
/@augments
/@extends
/@implements
Without Accompanying@param
/@description
/@example
/@returns
- Settings to Configure
check-types
andno-undefined-types
- Settings to Configure
valid-types
- Settings to Configure
require-returns
- Settings to Configure
require-example
- Settings to Configure
check-examples
- Allow
- Rules
check-alignment
check-examples
check-indentation
check-param-names
check-syntax
check-tag-names
check-types
implements-on-classes
match-description
newline-after-description
no-types
no-undefined-types
require-description-complete-sentence
require-description
require-example
require-hyphen-before-param-description
require-jsdoc
require-param-description
require-param-name
require-param-type
require-param
require-returns-check
require-returns-description
require-returns-type
require-returns
valid-types
Reference to jscs-jsdoc
This table maps the rules between eslint-plugin-jsdoc
and jscs-jsdoc
.
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 and specify eslint-plugin-jsdoc
as a plugin.
Finally, enable all of the rules that you would like to use.
Settings
@private
to disable rules for that comment block
Allow settings.jsdoc.ignorePrivate
- Disables all rules for the comment block on which it occurs.
require-jsdoc
Exempting empty functions from settings.jsdoc.exemptEmptyFunctions
- Will not report missing jsdoc blocks above functions/methods with no parameters or return values (intended where variable names are sufficient for themselves as documentation).
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.
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
Additional Tag Names
Use settings.jsdoc.additionalTagNames
to configure additional, allowed JSDoc
tags in the rule check-tag-names
. The format of the configuration is as follows:
@override
/@augments
/@extends
/@implements
Without Accompanying @param
/@description
/@example
/@returns
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
, or require-returns
).
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:
settings.jsdoc.allowOverrideWithoutParam
,
settings.jsdoc.allowImplementsWithoutParam
, and
settings.jsdoc.allowAugmentsExtendsWithoutParam
performed a similar function
but restricted to @param
. These settings are now deprecated.
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 (e.g.,'Array.<>': 'MyArray'
will changeArray.<string>
toMyArray.<string>
, preserving the dot; to get rid of the dot, you must use the pseudo-type:'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, i.e.,MyArray.<string>
will becomeMyArray<string>
butArray.<string>
will not be modified. - an object with the key
message
to provide a specific error message when encountering the discouraged type and, if a type is to be preferred in its place, the keyreplacement
to indicate the type that should be used in its place (and whichfix
mode can replace) orfalse
if forbidding the type. The message string will have the following substrings with special meaning replaced with their corresponding value ({{tagName}}
,{{tagValue}}
,{{badType}}
, and{{preferredType}}
(or{{replacement}}
), noting that the latter is of no use when one is merely forbidding a type).
- The "ANY" type,
If no-undefined-types
has the option key preferredTypesDefined
set to
true
, the preferred types indicated in the settings.jsdoc.preferredTypes
map will be assumed to be defined.
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>
).
valid-types
Settings to Configure settings.jsdoc.allowEmptyNamepaths
- Set tofalse
to disallow empty name paths with@callback
,@event
,@class
,@constructor
,@constant
,@const
,@function
,@func
,@method
,@interface
,@member
,@var
,@mixin
,@namespace
,@listens
,@fires
, or@emits
(these might often be expected to have an accompanying name path, though they have some indicative value without one; these may also allow names to be defined in another manner elsewhere in the block)settings.jsdoc.checkSeesForNamepaths
- Set this totrue
to insist that@see
only use name paths (the tag is normally permitted to allow other text)
require-returns
Settings to Configure settings.jsdoc.forceRequireReturn
- Set totrue
to always insist on@returns
documentation regardless of implicit or explicitreturn
's in the function. May be desired to flag that a project is aware of anundefined
/void
return.
require-example
Settings to Configure settings.jsdoc.avoidExampleOnConstructors
- Set totrue
to avoid the need for an example on a constructor (whether indicated as such by a jsdoc tag or by being within an ES6class
).
check-examples
Settings to Configure The settings below all impact the check-examples
rule and default to
no-op/false except as noted.
JSDoc specs use of an optional <caption>
element at the beginning of
@example
. The following setting requires its use.
settings.jsdoc.captionRequired
- Require<caption>
at beginning of any@example
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 settings determine whether a given
@example
tag will have the check-examples
checks applied to it:
settings.jsdoc.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]*)```$"
to only match explicitly fenced JavaScript blocks.settings.jsdoc.rejectExampleCodeRegex
- Regex blacklist which rejects non-lintable examples (has priority overexampleCodeRegex
). An example might be"^`"
to avoid linting fenced blocks which may indicate a non-JavaScript language.
If neither is in use, all examples will be matched. Note also that even if
settings.jsdoc.captionRequired
is not set, any initial <caption>
will be stripped out before doing the regex matching.
The following settings determine which individual ESLint rules will be
applied to the JavaScript found within the @example
tags (as determined
to be applicable by the above regex settings). They are ordered by
decreasing precedence:
settings.jsdoc.allowInlineConfig
- If not set tofalse
, will allow inline config within the@example
to override other config. Defaults totrue
.settings.jsdoc.noDefaultExampleRules
- Setting totrue
will disable the default rules which are expected to be troublesome for most documentation use. See the section below for the specific default rules.settings.jsdoc.matchingFileName
- Setting for a dummy file name to trigger specific rules defined in one's config; usable with ESLint.eslintrc.*
overrides
->files
globs, to apply a desired subset of rules with@example
(besides allowing for rules specific to examples, this setting can be useful for enabling reuse of the same rules within@example
as with JavaScript Markdown lintable by other plugins, e.g., if one setsmatchingFileName
todummy.md
so that@example
rules will follow one's Markdown rules).settings.jsdoc.configFile
- A config file. Corresponds to ESLint's-c
.settings.jsdoc.eslintrcForExamples
- Defaults totrue
in adding rules based on an.eslintrc.*
file. Setting tofalse
corresponds to ESLint's--no-eslintrc
.settings.jsdoc.baseConfig
- An object of rules with the same schema as.eslintrc.*
for defaults
Finally, the following rule pertains to inline disable directives:
settings.jsdoc.reportUnusedDisableDirectives
- If not set tofalse
, this will report disabled directives which are not used (and thus not needed). Defaults totrue
. Corresponds to ESLint's--report-unused-disable-directives
.
noDefaultExampleRules
is Set to true
Rules Disabled by Default Unless eol-last
- Insisting that a newline "always" be at the end is less likely to be desired in sample code as with the code file conventionno-console
- Unlikely to have inadvertent temporary debugging within examplesno-undef
- Many variables in examples will beundefined
.no-unused-vars
- It is common to define variables for clarity without always using them within examples.padded-blocks
- It can generally look nicer to pad a little even if one's code follows more stringency as far as block padding.import/no-unresolved
- One wouldn't generally expect example paths to resolve relative to the current JavaScript file as one would with real code.import/unambiguous
- Snippets in examples are likely too short to always include full import/export infonode/no-missing-import
- Seeimport/no-unresolved
node/no-missing-require
- Seeimport/no-unresolved
Rules
check-alignment
Reports invalid alignment of JSDoc block asterisks.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A |
The following patterns are considered problems:
/** * @param */ { }// Message: Expected JSDoc block to be aligned. /** * @param */ { }// Message: Expected JSDoc block to be aligned. /** * @param */ { }// Message: Expected JSDoc block to be aligned. /** * @param */ { }// Message: Expected JSDoc block to be aligned. /** * @param */ { }// Message: Expected JSDoc block to be aligned.
The following patterns are not considered problems:
/** * Desc * * @param */ { } /** * Desc * * @param {{ foo: Bar, bar: Baz * }} foo * */ { }
check-examples
Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.
Works in conjunction with the following settings:
captionRequired
exampleCodeRegex
rejectExampleCodeRegex
allowInlineConfig
- Defaults totrue
noDefaultExampleRules
matchingFileName
configFile
eslintrcForExamples
- Defaults totrue
baseConfig
reportUnusedDisableDirectives
- Defaults totrue
Inline ESLint config within @example
JavaScript is allowed, though the
disabling of ESLint directives which are not needed by the resolved rules
will be reported as with the ESLint --report-unused-disable-directives
command.
Context | ArrowFunctionExpression , ClassDeclaration , FunctionDeclaration , FunctionExpression |
Tags | example |
Settings | See above |
The following patterns are considered problems:
/** * @example alert('hello') */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}}// Message: @example error (no-alert): Unexpected alert. /** * @example alert('hello') */ // Settings: {"jsdoc":{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}}// Message: @example error (no-alert): Unexpected alert. /** * @example ```js alert('hello'); ``` */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}}// Message: @example error (semi): Extra semicolon. /** * @example * ```js alert('hello'); ``` */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}}// Message: @example error (semi): Extra semicolon. /** * @example ``` * js alert('hello'); ``` */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}}// Message: @example error (semi): Extra semicolon. /** * @example <b>Not JavaScript</b> */ { }/** * @example quux2(); */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>$"}}// Message: @example error (semi): Extra semicolon. /** * @example * quux(); // does something useful */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}// Message: @example error (no-undef): 'quux' is not defined. /** * @example <caption>Valid usage</caption> * quux(); // does something useful * * @example * quux('random unwanted arg'); // results in an error */ { }// Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}}// Message: Caption is expected for examples. /** * @example quux(); */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}}// Message: @example error (indent): Expected indentation of 0 spaces but found 1. /** * @example test() // eslint-disable-line semi */ {}// Settings: {"jsdoc":{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":true}}// Message: @example error: Unused eslint-disable directive (no problems were reported from 'semi'). /** * @example test() // eslint-disable-line semi */ {}// Settings: {"jsdoc":{"allowInlineConfig":false,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}// Message: @example error (semi): Missing semicolon.
The following patterns are not considered problems:
/** * @example ```js alert('hello'); ``` */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}} /** * @example * // arbitrary example content */ { }// Settings: {"jsdoc":{"eslintrcForExamples":false}} /** * @example * quux(); // does something useful */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}} /** * @example quux(); */ { }// Settings: {"jsdoc":{"baseConfig":{"rules":{"indent":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}} /** * @example <caption>Valid usage</caption> * quux(); // does something useful * * @example <caption>Invalid usage</caption> * quux('random unwanted arg'); // results in an error */ { }// Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}} /** * @example test() // eslint-disable-line semi */ {}// Settings: {"jsdoc":{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}} /** * @example test() // eslint-disable-line semi */ {}// Settings: {"jsdoc":{"allowInlineConfig":true,"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"noDefaultExampleRules":true}}
check-indentation
Reports invalid padding inside JSDoc block.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A |
The following patterns are considered problems:
/** * foo * * @param bar * baz */ { }// Message: There must be no indentation.
The following patterns are not considered problems:
/** * foo * * @param bar * baz */ { }
check-param-names
Ensures that parameter names in JSDoc match those in the function declaration.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
The following patterns are considered problems:
/** * @param Foo */ { }// Message: Expected @param names to be "foo". Got "Foo". /** * @arg Foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}// Message: Expected @arg names to be "foo". Got "Foo". /** * @param Foo */ { }// Message: Expected @param names to be "foo". Got "Foo". /** * @param Foo.Bar */ { }// Message: @param path declaration ("Foo.Bar") appears before any real parameter. /** * @param foo * @param Foo.Bar */ { }// Message: @param path declaration ("Foo.Bar") root node name ("Foo") does not match previous real parameter name ("foo"). /** * @param foo * @param foo.bar * @param bar */ { }// Message: Expected @param names to be "bar, foo". Got "foo, bar". /** * @param foo * @param bar */ { }// Message: @param "bar" does not match an existing function parameter. /** * @param foo * @param foo */ { }// Message: Duplicate @param "foo" /** * @param foo * @param foo */ { }// Message: Duplicate @param "foo" /** * @param foo * @param foo */ { }// Message: Duplicate @param "foo"
The following patterns are not considered problems:
/** * */ { } /** * @param foo */ { } /** * @param foo * @param bar */ { } /** * @param foo * @param bar */ { } /** * @param foo * @param foo.foo * @param bar */ { } /** * @param args */ { } /** * @param foo */ { } /** * @param foo */ { } /** * @param foo */ { } /** * Assign the project to a list of employees. * @param * @param * @param */ { };
Deconstructing Function Parameter
eslint-plugin-jsdoc
does not validate names of parameters in function deconstruction, e.g.
/** * @param foo */ { }
{a, b}
is an ObjectPattern
AST type and does not have a name. Therefore, the associated parameter in JSDoc block can have any name.
Likewise for the pattern [a, b]
which is an ArrayPattern
.
check-syntax
Reports against Google Closure Compiler syntax.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A |
The following patterns are considered problems:
/** * @param */ { }// Message: Syntax should not be Google Closure Compiler style.
The following patterns are not considered problems:
/** * @param */ { } /** * */ { }
check-tag-names
Reports invalid block tag names.
Valid JSDoc 3 Block Tags are:
abstract
access
alias
async
augments
author
borrows
callback
class
classdesc
constant
constructs
copyright
default
deprecated
description
enum
event
example
exports
external
file
fires
function
generator
global
hideconstructor
ignore
implements
inheritdoc
inner
instance
interface
kind
lends
license
listens
member
memberof
memberof!
mixes
mixin
module
name
namespace
override
package
param
private
property
protected
public
readonly
requires
returns
see
since
static
summary
this
throws
todo
tutorial
type
typedef
variation
version
yields
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A |
Settings | tagNamePreference , additionalTagNames |
The following patterns are considered problems:
/** * @Param */ { }// Message: Invalid JSDoc tag name "Param". /** * @foo */ { }// Message: Invalid JSDoc tag name "foo". /** * @arg foo */ { }// Message: Invalid JSDoc tag (preference). Replace "arg" JSDoc tag with "param". /** * @param foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg". /** * @param foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"parameter"}}}// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "parameter". /** * @bar foo */ { }// Message: Invalid JSDoc tag name "bar". /** * @baz @bar foo */ { }// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}// Message: Invalid JSDoc tag name "baz". /** * @bar * @baz */ { }// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}// Message: Invalid JSDoc tag name "baz".
The following patterns are not considered problems:
/** * @param foo */ { } /** * @memberof! foo */ { } /** * @arg foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}} /** * @bar foo */ { }// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}} /** * @baz @bar foo */ { }// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}} /** * @abstract * @access * @alias * @augments * @author * @borrows * @callback * @class * @classdesc * @constant * @constructs * @copyright * @default * @deprecated * @description * @enum * @event * @example * @exports * @external * @file * @fires * @function * @global * @ignore * @implements * @inheritdoc * @inner * @instance * @interface * @kind * @lends * @license * @listens * @member * @memberof * @memberof! * @mixes * @mixin * @module * @name * @namespace * @override * @param * @private * @property * @protected * @public * @readonly * @requires * @returns * @see * @since * @static * @summary * @this * @throws * @todo * @tutorial * @type * @typedef * @variation * @version */ {}
check-types
Reports invalid types.
By default, ensures that the casing of native types is the same as in this list:
undefined
null
boolean
number
string
object
Array
Function
Date
RegExp
Options
check-types
allows one option:
- An option object:
- with the key
noDefaults
to insist that only the supplied option type map is to be used, and that the default preferences (such as "string" over "String") will not be enforced. - with the key
unifyParentAndChildTypeChecks
which will treatsettings.jsdoc.preferredTypes
keys such asSomeType
as matching not only child types such as an unadornedSomeType
but alsoSomeType<aChildType>
,SomeType.<aChildType>
, or ifSomeType
isArray
(or[]
), it will matchaChildType[]
. If this isfalse
or unset, the former format will only apply to types which are not parent types/unions whereas the latter formats will only apply for parent types/unions. The special types[]
,.<>
(or.
), and<>
act only as parent types (and will not match a bare child type such asArray
even when unified, though, as mentioned,Array
will match saystring[]
orArray.<string>
when unified). The special type*
is only a child type. Note that there is no detection of parent and child type together, e.g., you cannot specify preferences forstring[]
specifically as distinct from saynumber[]
, but you can target both with[]
or the child typesnumber
orstring
.
- with the key
See also the documentation on settings.jsdoc.preferredTypes
which impacts
the behavior of check-types
.
Why not capital case everything?
Why are boolean
, number
and string
exempt from starting with a capital letter? Let's take string
as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as .toUpperCase()
.
Fortunately we don't have to write new String()
everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the GC has less work to do.
So in a sense, there two types of strings in Javascript; {string}
literals, also called primitives and {String}
Objects. We use the primitives because it's easier to write and uses less memory. {String}
and {string}
are technically both valid, but they are not the same.
'lard' // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}'lard' // "lard"'lard' === 'lard' // false
To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object.
However, Object.create(null)
objects are not instanceof Object
, however, so
in the case of this Object we lower-case to indicate possible support for
these objects.
Basically, for primitives, we want to define the type as a primitive, because that's what we use in 99.9% of cases. For everything else, we use the type rather than the primitive. Otherwise it would all just be {object}
.
In short: It's not about consistency, rather about the 99.9% use case. (And some functions might not even support the objects if they are checking for identity.)
type name | typeof |
check-types | testcase |
---|---|---|---|
Array | object | Array | ([]) instanceof Array -> true |
Function | function | function | (function f () {}) instanceof Function -> true |
Date | object | Date | (new Date()) instanceof Date -> true |
RegExp | object | RegExp | (new RegExp(/.+/)) instanceof RegExp -> true |
Object | object | object | ({}) instanceof Object -> true but Object.create(null) instanceof Object -> false |
Boolean | boolean | boolean | (true) instanceof Boolean -> false |
Number | number | number | (41) instanceof Number -> false |
String | string | string | ("test") instanceof String -> false |
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | class , constant , enum , implements , member , module , namespace , param , property , returns , throws , type , typedef , yields |
Aliases | constructor , const , var , arg , argument , prop , return , exception |
Closure-only | package , private , protected , public , static |
Options | noDefaults , unifyParentAndChildTypeChecks |
Settings | preferredTypes |
The following patterns are considered problems:
/** * @param */ { }// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number". /** * @arg */ { }// Message: Invalid JSDoc @arg "foo" type "Number"; prefer: "number". /** * @returns * @throws */ { }// Message: Invalid JSDoc @returns type "Number"; prefer: "number". /** * @param */ { }// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number". /** * @param {Array.<Number|String>} foo */ { }// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number". /** * @param */ { }// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":{"replacement":"Abc"},"string":"Str"}}}// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"; prefer: \"{{replacement}}\".","replacement":"Abc"},"string":"Str"}}}// Message: Messed up JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param * @param * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"; prefer: \"{{preferredType}}\".","replacement":"Abc"},"cde":{"message":"More messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"; prefer: \"{{preferredType}}\".","replacement":"Cde"},"object":"Object"}}}// Message: Messed up JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\".","replacement":false},"string":"Str"}}}// Message: Messed up JSDoc @param "foo" type "abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"."},"string":"Str"}}}// Message: Messed up JSDoc @param "foo" type "abc". /** * @param * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}// Options: [{"noDefaults":true}]// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":false,"string":"Str"}}}// Message: Invalid JSDoc @param "foo" type "abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":false}}}// Message: Invalid JSDoc @param "foo" type "abc". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"*":false,"abc":"Abc","string":"Str"}}}// Message: Invalid JSDoc @param "baz" type "*". /** * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"*":"aaa","abc":"Abc","string":"Str"}}}// Message: Invalid JSDoc @param "baz" type "*"; prefer: "aaa". /** * @param * @param */ {}// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"GenericArray"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "GenericArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"GenericArray","Array.<>":"GenericArray"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "GenericArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.<>":"GenericArray"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "GenericArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array<>":"GenericArray"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "GenericArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"SpecialTypeArray"}}}// Message: Invalid JSDoc @param "foo" type "[]"; prefer: "SpecialTypeArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"SpecialTypeArray"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "[]"; prefer: "SpecialTypeArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"SpecialTypeArray"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "SpecialTypeArray". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject","object.<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject","object<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object.<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object.<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object<>":"GenericObject"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":false}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":false}}}// Message: Invalid JSDoc @param "foo" type "object". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "object"; prefer: "GenericObject". /** * * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"Array."}}}// Message: Invalid JSDoc @param "foo" type "[]"; prefer: "Array.". /** * * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"Array.<>"}}}// Message: Invalid JSDoc @param "foo" type "[]"; prefer: "Array.<>". /** * * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"Array<>"}}}// Message: Invalid JSDoc @param "foo" type "[]"; prefer: "Array<>". /** * * @param {object.<string, object.<string, string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"object.":"Object"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object". /** * * @param {object.<string, object.<string, string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"object.":"Object<>"}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object<>". /** * * @param {object<string, object<string, string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"object<>":"Object."}}}// Message: Invalid JSDoc @param "foo" type "object"; prefer: "Object.". /** * * @param {Array.<Array.<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.":"[]"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "[]". /** * * @param {Array.<Array.<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.":"Array<>"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "Array<>". /** * * @param {Array.<Array.<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.":"<>"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "<>". /** * * @param {Array.<MyArray.<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.":"<>"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "<>". /** * * @param {Array.<MyArray.<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"MyArray.":"<>"}}}// Message: Invalid JSDoc @param "foo" type "MyArray"; prefer: "<>". /** * * @param {Array<Array<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"<>":"Array."}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "Array.". /** * * @param {Array<Array<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"Array."}}}// Options: [{"unifyParentAndChildTypeChecks":true}]// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "Array.". /** * * @param {Array<Array<string>>} foo */ { }// Settings: {"jsdoc":{"preferredTypes":{"<>":"[]"}}}// Message: Invalid JSDoc @param "foo" type "Array"; prefer: "[]".
The following patterns are not considered problems:
/** * @param * @param * @param */ { } /** * @arg * @arg * @arg */ { } /** * @param */ { } /** * @param {typeof bar} foo */ {} /** * @param {import('./foo').bar.baz} foo */ {} /** * @param {(x: number, y: string) => string} foo */ {} /** * @param {() => string} foo */ {} /** * @returns * @throws */ { }// Options: [{"noDefaults":true}] /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"Object"}}} /** * @param */ { } /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"GenericArray"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"GenericArray"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array":"SpecialTypeArray","Array.<>":"SpecialTypeArray","Array<>":"SpecialTypeArray"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.<>":"SpecialTypeArray","Array<>":"SpecialTypeArray"}}}// Options: [{"unifyParentAndChildTypeChecks":true}] /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"SpecialTypeArray"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"[]":"SpecialTypeArray"}}}// Options: [{"unifyParentAndChildTypeChecks":true}] /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array.<>":"GenericArray"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"Array<>":"GenericArray"}}} /** * @param */ { } /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object":"GenericObject"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object.<>":"GenericObject"}}} /** * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"object<>":"GenericObject"}}}
implements-on-classes
Reports an issue with any non-constructor function using @implements
.
Constructor functions, whether marked with @class
, @constructs
, or being
an ES6 class constructor, will not be flagged.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | implements (prevented) |
The following patterns are considered problems:
/** * @implements */ { }// Message: @implements used on a non-constructor function
The following patterns are not considered problems:
/** * @implements * @class */ { } /** * @implements * @constructor */ { } /** * */ /** * @implements */ { } /** * */ { }
match-description
Enforces a regular expression pattern on descriptions.
The default is this basic expression to match English sentences (Support for Unicode upper case may be added in a future version when it can be handled by our supported Node versions):
^([A-Z]|[`\\d_])([\\s\\S]*[.?!`])?$
You can supply your own expression passing a matchDescription
string on
the options object.
'jsdoc/match-description': 'error' matchDescription: '[A-Z].*\\.'
If you want different regular expressions to apply to tags, you may use
the tags
option object:
'jsdoc/match-description': 'error' tags: param: '\\- [A-Z].*\\.' returns: '[A-Z].*\\.'
In place of a string, you can also add true
to indicate that a particular
tag should be linted with the matchDescription
value (or the default).
'jsdoc/match-description': 'error' tags: param: true returns: true
By default, only the main function description is linted.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A by default but see tags options |
Settings | |
Options | tags (allows for 'param', 'arg', 'argument', 'returns', 'return'), matchDescription |
The following patterns are considered problems:
/** * foo. */ { }// Message: JSDoc description does not satisfy the regex pattern. /** * Foo) */ { }// Message: JSDoc description does not satisfy the regex pattern. /** * тест. */ { }// Options: [{"matchDescription":"[А-Я]+."}]// Message: JSDoc description does not satisfy the regex pattern. /** * Foo */ { }// Message: JSDoc description does not satisfy the regex pattern. /** * Foo. * * @param foo foo. */ { }// Options: [{"tags":{"param":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * Foo. * * @param foo bar */ { }// Options: [{"tags":{"param":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * {@see Foo.bar} buz */ { }// Message: JSDoc description does not satisfy the regex pattern. /** * Foo. * * @returns */ { }// Options: [{"tags":{"returns":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * Foo. * * @returns foo. */ { }// Options: [{"tags":{"returns":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * lorem ipsum dolor sit amet, consectetur adipiscing elit. pellentesque elit diam, * iaculis eu dignissim sed, ultrices sed nisi. nulla at ligula auctor, consectetur neque sed, * tincidunt nibh. vivamus sit amet vulputate ligula. vivamus interdum elementum nisl, * vitae rutrum tortor semper ut. morbi porta ante vitae dictum fermentum. * proin ut nulla at quam convallis gravida in id elit. sed dolor mauris, blandit quis ante at, * consequat auctor magna. duis pharetra purus in porttitor mollis. */ { }// Message: JSDoc description does not satisfy the regex pattern. /** * @arg */ { }// Options: [{"tags":{"arg":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * @argument */ { }// Options: [{"tags":{"argument":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * @return */ { }// Options: [{"tags":{"return":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * Returns bar. * * @return */ { }// Options: [{"tags":{"return":true}}]// Message: JSDoc description does not satisfy the regex pattern. /** * @param notRet * @returns Тест. */ { }// Options: [{"tags":{"param":"[А-Я]+."}}]// Message: JSDoc description does not satisfy the regex pattern.
The following patterns are not considered problems:
/** * @param foo - Foo. */ { }// Options: [{"tags":{"param":true}}] /** * Foo. */ { } /** * Foo. * Bar. */ { } /** * Foo. * * Bar. */ { } /** * Тест. */ { }// Options: [{"matchDescription":"[А-Я]+."}] /** * @param notRet * @returns Тест. */ { }// Options: [{"tags":{"returns":"[А-Я]+."}}] /** * Foo * bar. */ { } /** * @returns Foo bar. */ { }// Options: [{"tags":{"returns":true}}] /** * Foo. {@see Math.sin}. */ { } /** * Foo {@see Math.sin} bar. */ { } /** * Foo? * * Bar! * * Baz: * 1. Foo. * 2. Bar. */ { } /** * Hello: * World. */ { } /** * Hello: world. */ { } /** * Foo * Bar. */ { } /** * Foo. * * foo. */ { }
newline-after-description
Enforces a consistent padding of the block description.
This rule takes one argument. If it is "always"
then a problem is raised when there is a newline after the description. If it is "never"
then a problem is raised when there is no newline after the description. The default value is "always"
.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | N/A |
The following patterns are considered problems:
/** * Foo. * * Foo. * @foo */ { }// Options: ["always"]// Message: There must be a newline after the description of the JSDoc block. /** * Bar. * * Bar. * * @bar */ { }// Options: ["never"]// Message: There must be no newline after the description of the JSDoc block.
The following patterns are not considered problems:
/** * Foo. */ { }// Options: ["always"] /** * Bar. */ { }// Options: ["never"] /** * Foo. * * @foo */ { }// Options: ["always"] /** * Bar. * @bar */ { }// Options: ["never"]
no-types
This rule reports types being used on @param
or @returns
.
The rule is intended to prevent the indication of types on tags where the type information would be redundant with TypeScript.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param , returns |
Aliases | arg , argument , return |
The following patterns are considered problems:
/** * @param */ { }// Message: Types are not permitted on @param. /** * @returns */ { }// Message: Types are not permitted on @returns.
The following patterns are not considered problems:
/** * @param foo */ { }
no-undefined-types
Checks that types in jsdoc comments are defined. This can be used to check unimported types.
When enabling this rule, types in jsdoc comments will resolve as used
variables, i.e. will not be marked as unused by no-unused-vars
.
In addition to considering globals found in code (or in ESLint-indicated
globals
) as defined, the following tags will also be checked for
name(path) definitions to also serve as a potential "type" for checking
the tag types in the table below:
@callback
, @class
(or @constructor
), @constant
(or @const
), @event
, @external
(or @host
), @function
(or @func
or @method
), @interface
, @member
(or @var
), @mixin
, @name
, @namespace
, @typedef
.
The following types are always considered defined.
null
,undefined
,string
,boolean
,object
,function
number
,NaN
,Infinity
any
,*
Array
,Object
,RegExp
,Date
,Function
Options
An option object may have the following keys:
preferredTypesDefined
- If this option is set totrue
and preferred types are indicated withinsettings.jsdoc.preferredTypes
, any such types will be assumed to be defined as well.definedTypes
- This array can be populated to indicate other types which are automatically considered as defined (in addition to globals, etc.)
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | class , constant , enum , implements , member , module , namespace , param , property , returns , throws , type , typedef , yields |
Aliases | constructor , const , var , arg , argument , prop , return , exception , yield |
Closure-only | package , private , protected , public , static |
Options | preferredTypesDefined , definedTypes |
Settings | preferredTypes |
The following patterns are considered problems:
/** * @param */ { }// Message: The type 'strnig' is undefined. /*** @param* @param*/ { }// Options: [{"definedTypes":["MyType"]}]// Message: The type 'HisType' is undefined. /** * @param * @param * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType"}}}}// Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]// Message: The type 'HisType' is undefined. /** * @param * @param * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":false},"histype":"HisType"}}}// Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]// Message: The type 'HerType' is undefined.
The following patterns are not considered problems:
/** * @param */ { } /** * @param */ { } {} /** * @param */ { console;} ; const MyType = MyType; /** * @param */ { } const MyType = MyType; /** * @param */ { } ; /** * @param * @param * @param */ { } /*globals MyType*/ /** * @param * @param */ { } /** * @typedef * @property */ /** * @param */ { } /** * @param {Array<syntaxError} foo */ { } /** * Callback test. * * @callback addStuffCallback * @param *//** * Test Eslint. * * @param */ { ;} /** * * */ { } /*** @param* @param*/ { }// Options: [{"definedTypes":["MyType","HisType"]}] /** * @param * @param * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType"},"histype":"HisType"}}}// Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}] /** * @param * @param * @param */ { }// Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType<>"},"histype":"HisType.<>"}}}// Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
require-description-complete-sentence
Requires that block description and tag description are written in complete sentences, i.e.,
- Description must start with an uppercase alphabetical character.
- Paragraphs must start with an uppercase alphabetical character.
- Sentences must end with a period.
- Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param , returns |
Aliases | arg , argument , return |
The following patterns are considered problems:
/** * foo. */ { }// Message: Sentence should start with an uppercase character. /** * Foo) */ { }// Message: Sentence must end with a period. /** * Foo. * * foo. */ { }// Message: Sentence should start with an uppercase character. /** * тест. */ { }// Message: Sentence should start with an uppercase character. /** * Foo */ { }// Message: Sentence must end with a period. /** * Foo * Bar. */ { }// Message: A line of text is started with an uppercase character, but preceding line does not end the sentence. /** * Foo. * * @param foo foo. */ { }// Message: Sentence should start with an uppercase character. /** * Foo. * * @param foo bar */ { }// Message: Sentence should start with an uppercase character. /** * {@see Foo.bar} buz */ { }// Message: Sentence should start with an uppercase character. /** * Foo. * * @returns */ { }// Message: Sentence should start with an uppercase character. /** * Foo. * * @returns foo. */ { }// Message: Sentence should start with an uppercase character. /** * lorem ipsum dolor sit amet, consectetur adipiscing elit. pellentesque elit diam, * iaculis eu dignissim sed, ultrices sed nisi. nulla at ligula auctor, consectetur neque sed, * tincidunt nibh. vivamus sit amet vulputate ligula. vivamus interdum elementum nisl, * vitae rutrum tortor semper ut. morbi porta ante vitae dictum fermentum. * proin ut nulla at quam convallis gravida in id elit. sed dolor mauris, blandit quis ante at, * consequat auctor magna. duis pharetra purus in porttitor mollis. */ { }// Message: Sentence should start with an uppercase character. /** * @arg */ { }// Message: Sentence must end with a period. /** * @argument */ { }// Message: Sentence must end with a period. /** * @return */ { }// Message: Sentence should start with an uppercase character. /** * Returns bar. * * @return */ { }// Message: Sentence should start with an uppercase character.
The following patterns are not considered problems:
/** * @param foo - Foo. */ { } /** * Foo. */ { } /** * Foo. * Bar. */ { } /** * Foo. * * Bar. */ { } /** * Тест. */ { } /** * Foo * bar. */ { } /** * @returns Foo bar. */ { } /** * Foo. {@see Math.sin}. */ { } /** * Foo {@see Math.sin} bar. */ { } /** * Foo? * * Bar! * * Baz: * 1. Foo. * 2. Bar. */ { } /** * Hello: * World. */ { } /** * Hello: world. */ { }
require-description
Requires that all functions have a description.
- All functions must have a
@description
tag. - Every description tag must have a non-empty description that explains the purpose of the method.
Options
contexts
- Set to a string or array of strings representing the AST context where you wish the rule to be applied (e.g.,ClassDeclaration
for ES6 classes).noDefaults
- By default,contexts
will permitArrowFunctionExpression
,FunctionDeclaration
, andFunctionExpression
. Set this instead totrue
to havecontexts
override these.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression ; others when contexts option enabled |
Tags | description |
Aliases | desc |
Options | contexts , noDefaults |
The following patterns are considered problems:
/** * */ { }// Message: Missing JSDoc @description declaration. /** * */ // Options: [{"contexts":"ClassDeclaration"}]// Message: Missing JSDoc @description declaration. /** * */ // Options: [{"contexts":"ClassDeclaration","noDefaults":true}]// Message: Missing JSDoc @description declaration. /** * */ // Options: [{"contexts":["ClassDeclaration"]}]// Message: Missing JSDoc @description declaration. /** * @description */ { }// Message: Missing JSDoc @description description.
The following patterns are not considered problems:
/** * @description * // arbitrary description content */ { } /** * @description * quux(); // does something useful */ { } /** * @description <caption>Valid usage</caption> * quux(); // does something useful * * @description <caption>Invalid usage</caption> * quux('random unwanted arg'); // results in an error */ { } /** * */ /** * */ { }// Options: [{"noDefaults":true}]
require-example
Requires that all functions have examples.
- All functions must have one or more
@example
tags. - Every example tag must have a non-empty description that explains the method's usage.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | example |
Settings | avoidExampleOnConstructors |
The following patterns are considered problems:
/** * */ { }// Message: Missing JSDoc @example declaration. /** * @example */ { }// Message: Missing JSDoc @example description. /** * @constructor */ { }// Message: Missing JSDoc @example declaration. /** * @constructor * @example */ { }// Message: Missing JSDoc @example description.
The following patterns are not considered problems:
/** * @example * // arbitrary example content */ { } /** * @example * quux(); // does something useful */ { } /** * @example <caption>Valid usage</caption> * quux(); // does something useful * * @example <caption>Invalid usage</caption> * quux('random unwanted arg'); // results in an error */ { } /** * @constructor */ { }// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}} /** * @constructor * @example */ { }// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}} /** * @inheritdoc */ { }
require-hyphen-before-param-description
Requires a hyphen before the @param
description.
This rule takes one argument. If it is "always"
then a problem is raised when there is no hyphen before the description. If it is "never"
then a problem is raised when there is a hyphen before the description. The default value is "always"
.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
Aliases | arg , argument |
The following patterns are considered problems:
/** * @param foo Foo. */ { }// Options: ["always"]// Message: There must be a hyphen before @param description. /** * @param foo - Foo. */ { }// Options: ["never"]// Message: There must be no hyphen before @param description. /** * @param foo - foo * @param foo foo */ { }// Options: ["always"]// Message: There must be a hyphen before @param description. /** * @param foo foo * bar * @param bar - bar */ { }// Options: ["always"]// Message: There must be a hyphen before @param description.
The following patterns are not considered problems:
/** * @param foo - Foo. */ { }// Options: ["always"] /** * @param foo Foo. */ { }// Options: ["never"]
require-jsdoc
Checks for presence of jsdoc comments, on class declarations as well as functions.
Context | ArrowFunctionExpression , ClassDeclaration , FunctionDeclaration , FunctionExpression |
Tags | N/A |
Settings | exemptEmptyFunctions |
The following patterns are considered problems:
{ }// Message: Missing JSDoc comment. {}// Message: Missing JSDoc comment. /** * Description for A. */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]// Message: Missing JSDoc comment. /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]// Message: Missing JSDoc comment. /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]// Message: Missing JSDoc comment. /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]// Message: Missing JSDoc comment. /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]// Message: Missing JSDoc comment. var {}// Options: [{"require":{"ArrowFunctionExpression":true}}]// Message: Missing JSDoc comment. var {}// Options: [{"require":{"ArrowFunctionExpression":true}}]// Message: Missing JSDoc comment. var {}// Options: [{"require":{"FunctionExpression":true}}]// Message: Missing JSDoc comment. const foo = {}// Options: [{"require":{"FunctionExpression":true}}]// Message: Missing JSDoc comment. var foo = {}// Options: [{"require":{"FunctionExpression":true}}]// Message: Missing JSDoc comment. {}// Settings: {"jsdoc":{"exemptEmptyFunctions":false}}// Message: Missing JSDoc comment. { return true;}// Settings: {"jsdoc":{"exemptEmptyFunctions":false}}// Message: Missing JSDoc comment.
The following patterns are not considered problems:
var array = 123;array; /** * @class MyClass **/ {} /** Function doing something */ {}/** Function doing something */var {};/** Function doing something */Object {};var obj = /** * Function doing something **/ {} ; /** @func myFunction */ {}/** @method myFunction */ {}/** @function myFunction */ {} /** @func myFunction */var {}/** @method myFunction */var {}/** @function myFunction */var {} /** @func myFunction */Object {}/** @method myFunction */Object {}/** @function myFunction */Object {}{}; var object = /** * @func myFunction - Some function */ {} var object = /** * @method myFunction - Some function */ {} var object = /** * @function myFunction - Some function */ {} var array = 123;array;Object;var object = name: 'key';Object {}// Options: [{"require":{"ClassDeclaration":true,"FunctionDeclaration":false,"MethodDefinition":true}}] var {}// Options: [{"require":{"ClassDeclaration":true,"FunctionDeclaration":false,"MethodDefinition":true}}] /** * Description for A. */ /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}] /** * Description for A. */ /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}] /** * Description for A. */ /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}] /** * Description for A. */ /** * Description for constructor. * @param */ { thisa = xs; }// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}] { thisa = xs; }// Options: [{"require":{"ClassDeclaration":false,"MethodDefinition":false}}] /** Function doing something*/var {}// Options: [{"require":{"ArrowFunctionExpression":true}}] /** Function doing something*/var {}// Options: [{"require":{"ArrowFunctionExpression":true}}] ;// Options: [{"require":{"ArrowFunctionExpression":true}}] /**JSDoc Block*/var {}// Options: [{"require":{"FunctionExpression":true}}] const foo = /**JSDoc Block*/ {}// Options: [{"require":{"FunctionExpression":true}}] var foo = /**JSDoc Block*/ {}// Options: [{"require":{"FunctionExpression":true}}] var foo = {}: 1 ;// Options: [{"require":{"FunctionExpression":true}}] {}// Settings: {"jsdoc":{"exemptEmptyFunctions":true}} { return;}// Settings: {"jsdoc":{"exemptEmptyFunctions":true}}
require-param-description
Requires that @param
tag has description
value.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
Aliases | arg , argument |
The following patterns are considered problems:
/** * @param foo */ { }// Message: Missing JSDoc @param "foo" description. /** * @arg foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}// Message: Missing JSDoc @arg "foo" description.
The following patterns are not considered problems:
/** * */ { } /** * @param foo Foo. */ { }
require-param-name
Requires that all function parameters have name.
The
@param
tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
Aliases | arg , argument |
The following patterns are considered problems:
/** * @param */ { }// Message: There must be an identifier after @param type. /** * @param */ { }// Message: There must be an identifier after @param tag.
The following patterns are not considered problems:
/** * @param foo */ { } /** * @param */ { }
require-param-type
Requires that @param
tag has type
value.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
Aliases | arg , argument |
The following patterns are considered problems:
/** * @param foo */ { }// Message: Missing JSDoc @param "foo" type. /** * @arg foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}// Message: Missing JSDoc @arg "foo" type.
The following patterns are not considered problems:
/** * */ { } /** * @param */ { }
require-param
Requires that all function parameters are documented.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
Aliases | arg , argument |
Settings | allowOverrideWithoutParam , allowImplementsWithoutParam , allowAugmentsExtendsWithoutParam |
The following patterns are considered problems:
/** * */ { }// Message: Missing JSDoc @param "foo" declaration. /** * */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}// Message: Missing JSDoc @arg "foo" declaration. /** * @param foo */ { }// Message: Missing JSDoc @param "bar" declaration. /** * @override */ { }// Settings: {"jsdoc":{"allowOverrideWithoutParam":false}}// Message: Missing JSDoc @param "foo" declaration. /** * @implements */ { }// Settings: {"jsdoc":{"allowImplementsWithoutParam":false}}// Message: Missing JSDoc @param "foo" declaration. /** * @augments */ { }// Message: Missing JSDoc @param "foo" declaration. /** * @extends */ { }// Message: Missing JSDoc @param "foo" declaration. /** * @override */ /** * */ { }// Settings: {"jsdoc":{"allowOverrideWithoutParam":false}}// Message: Missing JSDoc @param "foo" declaration. /** * @implements */ /** * */ { }// Settings: {"jsdoc":{"allowImplementsWithoutParam":false}}// Message: Missing JSDoc @param "foo" declaration. /** * @augments */ /** * */ { }// Message: Missing JSDoc @param "foo" declaration. /** * @extends */ /** * */ { }// Message: Missing JSDoc @param "foo" declaration.
The following patterns are not considered problems:
/** * @param foo */ { } /** * @inheritdoc */ { } /** * @arg foo */ { }// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}} /** * @override * @param foo */ { } /** * @override */ { } /** * @override */ /** * */ { } /** * @override */ { }// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}} /** * @implements */ /** * */ { } /** * @implements */ { } /** * @implements */ { }// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}} /** * @implements * @param foo */ { } /** * @augments */ { }// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}} /** * @augments * @param foo */ { } /** * @extends */ { }// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}} /** * @extends * @param foo */ { } /** * @override */ /** * @param foo */ { } /** * @override */ /** * */ { }// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}} /** * @implements */ /** * */ { }// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}} /** * @implements */ /** * @param foo */ { } /** * @augments */ /** * */ { }// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}} /** * @augments */ /** * @param foo */ { } /** * @extends */ /** * */ { }// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}} /** * @extends */ /** * @param foo */ { } /** * @private */ { }// Settings: {"jsdoc":{"ignorePrivate":true}} // issue 182: optional chaining/** @const */const test = something?
require-returns-check
Checks if the return expression exists in function body and in the comment.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | returns |
Aliases | return |
The following patterns are considered problems:
/** * @returns */ { }// Message: JSDoc @returns declaration present but return expression not available in function. /** * @return */ { }// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}// Message: JSDoc @return declaration present but return expression not available in function. /** * @returns */const quux = {}// Message: JSDoc @returns declaration present but return expression not available in function. /** * @returns * @returns */ { return foo;}// Message: Found more than one @returns declaration. const language = /** * @param * @returns */ { this_name = name; }// Message: JSDoc @returns declaration present but return expression not available in function.
The following patterns are not considered problems:
/** * @returns Foo. */ { return foo;} /** * @returns */ { return foo;} /** * @returns */ { return foo;} /** * */ {} /** * @returns */const quux = foo; /** * @returns */ {} /** * @returns { void } Foo. */ {} /** * @returns */ {} /** * @returns */const quux = {} /** * @returns */const quux = async {} /** * @returns Foo. * @abstract */ { throw 'must be implemented by subclass!';} /** * @returns Foo. * @virtual */ { throw 'must be implemented by subclass!';} /** * @returns Foo. * @constructor */ {} /** * @returns */ {} /** * @returns */ {} /** * @returns */ { return undefined;} /** * @returns */ { return;} /** * */ { return undefined;} /** * */ { return;}
require-returns-description
Requires that @returns
tag has description
value.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | returns |
Aliases | return |
The following patterns are considered problems:
/** * @returns */ { }// Message: Missing JSDoc @returns description. /** * @return */ { }// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}// Message: Missing JSDoc @return description.
The following patterns are not considered problems:
/** * */ { } /** * @returns Foo. */ { } /** * @returns */ { } /** * @returns */ { }
require-returns-type
Requires that @returns
tag has type
value.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | returns |
Aliases | return |
The following patterns are considered problems:
/** * @returns */ { }// Message: Missing JSDoc @returns type. /** * @returns Foo. */ { }// Message: Missing JSDoc @returns type. /** * @return Foo. */ { }// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}// Message: Missing JSDoc @return type.
The following patterns are not considered problems:
/** * @returns */ { }
require-returns
Requires returns are documented.
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | returns |
Aliases | return |
Settings | forceRequireReturn |
The following patterns are considered problems:
/** * */ { return foo;}// Message: Missing JSDoc @returns declaration. /** * */const foo = bar: 'baz'// Message: Missing JSDoc @returns declaration. /** * */const foo = bar // Message: Missing JSDoc @returns declaration. /** * */const foo = bar// Message: Missing JSDoc @returns declaration. /** * */ { return foo;}// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}// Message: Missing JSDoc @return declaration. /** * */ {}// Message: Missing JSDoc @returns declaration. /** * */const quux = {}// Message: Missing JSDoc @returns declaration. /** * */const quux = async {}// Message: Missing JSDoc @returns declaration. /** * */ {}// Settings: {"jsdoc":{"forceRequireReturn":true}}// Message: Missing JSDoc @returns declaration. const language = /** * @param */ { return this_name; }// Message: Missing JSDoc @returns declaration.
The following patterns are not considered problems:
/** * @returns Foo. */ { return foo;} /** * */ {} /** * */ { bar} /** * @returns Array */ { return bar} /** * @returns Array */const quux = bar /** * @inheritdoc */ {} /** * @override */ {} /** * @constructor */ {} /** * @implements */ {} /** * @override */ { return foo;} /** * @class */ { } /** * @constructor */ { } /** * @returns */ { return a: foo;} /** * @returns */const quux = a: foo; /** * @returns */const quux = { return a: foo}; /** * @returns */ {} /** * @returns */const quux = { } /** * @returns */ {} /** * @returns */const quux = { } /** * */ {} /** * */const quux = { } /** * */ { }// Settings: {"jsdoc":{"forceRequireReturn":true}} const language = /** * @param */ { this_name = name; } /** * @returns */ {}// Settings: {"jsdoc":{"forceRequireReturn":true}} /** * @returns */ { return undefined;} /** * @returns */ { return undefined;}// Settings: {"jsdoc":{"forceRequireReturn":true}} /** * @returns */ { return;} /** * @returns */ {}// Settings: {"jsdoc":{"forceRequireReturn":true}} /** * @returns */ { return;}// Settings: {"jsdoc":{"forceRequireReturn":true}} /** foo class */ /** foo constructor */ { // => thisbar = true; } ;
valid-types
Requires all types to be valid JSDoc or Closure compiler types without syntax errors.
Also impacts behaviors on namepath (or event)-defining and pointing tags:
- Name(path)-defining tags requiring namepath:
@external
,@host
,@name
,@typedef
- Name(path)-defining tags (which may have value without namepath or their
namepath can be expressed elsewhere on the block):
@event
,@callback
,@class
,@constructor
,@constant
,@const
,@function
,@func
,@method
,@interface
,@member
,@var
,@mixin
,@namespace
- Name(path)-pointing tags requiring namepath:
@alias
,@augments
,@extends
,@lends
,@memberof
,@memberof!
,@mixes
,@this
- Name(path)-pointing tags (which may have value without namepath or their
namepath can be expressed elsewhere on the block):
@listens
,@fires
,@emits
- Name(path)-pointing tags (multiple names in one):
@borrows
...with the following applying to the above sets:
- Expect tags in set 1-4 to have a valid namepath if present
- Prevent sets 2 and 4 from being empty by setting
allowEmptyNamepaths
tofalse
as these tags might have some indicative value without a path or may allow a name expressed elsewhere on the block (but sets 1 and 3 will always fail if empty) - For the special case of set 5, i.e.,
@borrows <that namepath> as <this namepath>
, check that both namepaths are present and valid and ensure there is anas
between them. - For the special case of
@memberof
and@memberof!
(part of set 3), as per the specification, they also allow#
,.
, or~
at the end (which is not allowed at the end of normal paths).
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | For name only unless otherwise stated: alias , augments , borrows , callback , class (for name and type), constant (for name and type), enum (for type), event , external , fires , function , implements (for type), interface , lends , listens , member (for name and type), memberof , memberof! , mixes , mixin , module (for name and type), name , namespace (for name and type), param (for name and type), property (for name and type), returns (for type), this , throws (for type), type (for type), typedef (for name and type), yields (for type) |
Aliases | extends , constructor , const , host , emits , func , method , var , arg , argument , prop , return , exception , yield |
Closure-only | For type only: package , private , protected , public , static |
Settings | allowEmptyNamepaths , checkSeesForNamepaths |
The following patterns are considered problems:
/** * @param {Array<string} foo */ { }// Message: Syntax error in type: Array<string /** * @borrows foo% as bar */ { }// Message: Syntax error in type: foo% /** * @borrows foo as bar% */ { }// Message: Syntax error in type: bar% /** * @borrows foo */ { }// Message: @borrows must have an "as" expression. Found "" /** * @see foo% */ { }// Settings: {"jsdoc":{"checkSeesForNamepaths":true}}// Message: Syntax error in type: foo% /** * @alias module:abc#event:foo-bar */ { }// Message: Syntax error in type: module:abc#event:foo-bar /** * @mixes module:namespace.SomeClass~ */ { }// Message: Syntax error in type: module:namespace.SomeClass~ /** * @callback */ { }// Settings: {"jsdoc":{"allowEmptyNamepaths":false}}// Message: Syntax error in type:
The following patterns are not considered problems:
/** * @param */ { } /** * @param */ { } /** * @param foo */ { } /** * @borrows foo as bar */ { } /** * @see foo% */ { } /** * @alias module:namespace.SomeClass#event:ext_anevent */ { } /** * @callback */ { } /** * @class */ { } /** * @see */ { } /** * * @fires {module:namespace.SomeClass#event:ext_anevent} */ { } /** * @memberof module:namespace.SomeClass~ */ { } /** * @memberof! module:namespace.SomeClass. */ { }