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
    • Allow @override Without Accompanying @param Tags
    • Settings to Configure check-types and no-undefined-types
    • Settings to Configure valid-types
    • Settings to Configure require-returns
    • Settings to Configure require-example
    • Settings to Configure check-examples
  • 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.

eslint-plugin-jsdoc	jscs-jsdoc
check-alignment	N/A
check-examples	N/A
check-indentation	N/A
check-param-names	checkParamNames
check-syntax	N/A
check-tag-names	N/A ~ checkAnnotations
check-types	checkTypes
newline-after-description	requireNewlineAfterDescription and disallowNewlineAfterDescription
require-description	N/A
require-description-complete-sentence	requireDescriptionCompleteSentence
require-example	N/A
require-hyphen-before-param-description	requireHyphenBeforeDescription
require-param	checkParamExistence
require-param-description	requireParamDescription
require-param-name	N/A
require-param-type	requireParamTypes
require-returns	requireReturn
require-returns-check	requireReturn
require-returns-description	requireReturnDescription
require-returns-type	requireReturnTypes
valid-types	N/A
no-undefined-types	N/A
N/A	checkReturnTypes
N/A	checkRedundantParams
N/A	checkReturnTypes
N/A	checkRedundantAccess
N/A	enforceExistence
N/A	leadingUnderscoreAccess

Installation

Install ESLint either locally or globally.

npm install eslint

If you have installed ESLint globally, you have to install JSDoc plugin globally too. Otherwise, install it locally.

npm install eslint-plugin-jsdoc

Configuration

Add plugins section 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-alignment": 1,
        "jsdoc/check-examples": 1,
        "jsdoc/check-indentation": 1,
        "jsdoc/check-param-names": 1,
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1,
        "jsdoc/check-types": 1,
        "jsdoc/implements-on-classes": 1,
        "jsdoc/match-description": 1,
        "jsdoc/newline-after-description": 1,
        "jsdoc/no-types": 1,
        "jsdoc/no-undefined-types": 1,
        "jsdoc/require-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-example": 1,
        "jsdoc/require-hyphen-before-param-description": 1,
        "jsdoc/require-jsdoc": 1,
        "jsdoc/require-param": 1,
        "jsdoc/require-param-description": 1,
        "jsdoc/require-param-name": 1,
        "jsdoc/require-param-type": 1,
        "jsdoc/require-returns": 1,
        "jsdoc/require-returns-check": 1,
        "jsdoc/require-returns-description": 1,
        "jsdoc/require-returns-type": 1,
        "jsdoc/valid-types": 1
    }
}

Settings

Allow @private to disable rules for that comment block

• settings.jsdoc.allowPrivate - Disables all rules for the comment block on which it occurs.

Exempting empty functions from require-jsdoc

• 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.

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "param": "arg",
                "returns": "return"
            }
        }
    }
}

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:

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "additionalTagNames": {
                "customTags": ["define", "extends", "record"]
            }
        }
    }
}

Allow @override Without Accompanying @param Tags

Use any of the following settings to override require-param and allow @param to be omitted when the specified tags are present on the JSDoc comment or the parent class comment. The default value for each is false.

• settings.jsdoc.allowOverrideWithoutParam - Enables behavior with @override tag
• settings.jsdoc.allowImplementsWithoutParam - Enables behavior with @implements tag
• settings.jsdoc.allowAugmentsExtendsWithoutParam - Enables behavior with @augments tag or its synonym @extends

The format of the configuration is as follows:

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "allowOverrideWithoutParam": true,
            "allowImplementsWithoutParam": true,
            "allowAugmentsExtendsWithoutParam": true
        }
    }
}

Settings to Configure check-types and no-undefined-types

• 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 for check-types). The keys of this map are the types to be replaced (or forbidden) and can include the "ANY" type, *. 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)
  • 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 key replacement to indicate the type that should be used in its place (and which fix mode can replace) or false 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}}, noting that the latter is of no use when one is merely forbidding a 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.

Settings to Configure valid-types

• settings.jsdoc.allowEmptyNamepaths - Set to false to disallow empty name paths with @callback, @event, @listens, @fires, or @emits (these might often be expected to have an accompanying name path, though they have some indicative value without one)
• settings.jsdoc.checkSeesForNamepaths - Set this to true to insist that @see only use name paths (the tag is normally permitted to allow other text)

Settings to Configure require-returns

• settings.jsdoc.forceRequireReturn - Set to true to always insist on @returns documentation regardless of implicit or explicit return's in the function. May be desired to flag that a project is aware of an undefined/void return.

Settings to Configure require-example

• settings.jsdoc.avoidExampleOnConstructors - Set to true to avoid the need for an example on a constructor (whether indicated as such by a jsdoc tag or by being within an ES6 class).

Settings to Configure check-examples

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 over exampleCodeRegex). 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 to false, will allow inline config within the @example to override other config. Defaults to true.
• settings.jsdoc.noDefaultExampleRules - Setting to true 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 sets matchingFileName to dummy.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 to true in adding rules based on an .eslintrc.* file. Setting to false 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 to false, this will report disabled directives which are not used (and thus not needed). Defaults to true. Corresponds to ESLint's --report-unused-disable-directives.

Rules Disabled by Default Unless noDefaultExampleRules is Set to true

• 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 convention
• no-console - Unlikely to have inadvertent temporary debugging within examples
• no-undef - Many variables in examples will be undefined.
• 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 info
• node/no-missing-import - See import/no-unresolved
• node/no-missing-require - See import/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 {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.

/**
 * @param {Number} foo
 */
function quux (foo) {

}
// 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) {

}

check-examples

Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.

Works in conjunction with the following settings:

• captionRequired
• exampleCodeRegex
• rejectExampleCodeRegex
• allowInlineConfig - Defaults to true
• noDefaultExampleRules
• matchingFileName
• configFile
• eslintrcForExamples - Defaults to true
• baseConfig
• reportUnusedDisableDirectives - Defaults to true

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')
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}}
// Message: @example error (no-alert): Unexpected alert.

/**
 * @example alert('hello')
 */
class quux {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"eslintrcForExamples":false}}
// Message: @example error (no-alert): Unexpected alert.

/**
 * @example ```js
 alert('hello');
 ```
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}}
// Message: @example error (semi): Extra semicolon.

/**
 * @example
 * ```js alert('hello'); ```
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}}
// Message: @example error (semi): Extra semicolon.

/**
 * @example ```
 * js alert('hello'); ```
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}}
// Message: @example error (semi): Extra semicolon.

/**
 * @example <b>Not JavaScript</b>
 */
function quux () {

}
/**
 * @example quux2();
 */
function quux2 () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","never"]}},"eslintrcForExamples":false,"rejectExampleCodeRegex":"^\\s*<.*>$"}}
// Message: @example error (semi): Extra semicolon.

/**
 * @example
 * quux(); // does something useful
 */
function quux () {

}
// 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
 */
function quux () {

}
// Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}}
// Message: Caption is expected for examples.

/**
 * @example  quux();
 */
function 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
 */
function quux () {}
// 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
 */
function quux () {}
// 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');
 ```
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"semi":["error","always"]}},"eslintrcForExamples":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}}

/**
 * @example
 * // arbitrary example content
 */
function quux () {

}
// Settings: {"jsdoc":{"eslintrcForExamples":false}}

/**
 * @example
 * quux(); // does something useful
 */
function quux () {

}
// Settings: {"jsdoc":{"baseConfig":{"rules":{"no-undef":["error"]}},"eslintrcForExamples":false,"noDefaultExampleRules":false}}

/**
 * @example quux();
 */
function 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
 */
function quux () {

}
// Settings: {"jsdoc":{"captionRequired":true,"eslintrcForExamples":false}}

/**
 * @example test() // eslint-disable-line semi
 */
function quux () {}
// Settings: {"jsdoc":{"eslintrcForExamples":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}}

/**
 * @example
 test() // eslint-disable-line semi
 */
function quux () {}
// 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
 */
function quux () {

}
// Message: There must be no indentation.

The following patterns are not considered problems:

/**
 * foo
 *
 * @param bar
 * baz
 */
function quux () {

}

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
 */
function quux (foo = 'FOO') {

}
// Message: Expected @param names to be "foo". Got "Foo".

/**
 * @arg Foo
 */
function quux (foo = 'FOO') {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
// Message: Expected @arg names to be "foo". Got "Foo".

/**
 * @param Foo
 */
function quux (foo) {

}
// Message: Expected @param names to be "foo". Got "Foo".

/**
 * @param Foo.Bar
 */
function quux (foo) {

}
// Message: @param path declaration ("Foo.Bar") appears before any real parameter.

/**
 * @param foo
 * @param Foo.Bar
 */
function quux (foo) {

}
// 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
 */
function quux (bar, foo) {

}
// Message: Expected @param names to be "bar, foo". Got "foo, bar".

/**
 * @param foo
 * @param bar
 */
function quux (foo) {

}
// Message: @param "bar" does not match an existing function parameter.

/**
 * @param foo
 * @param foo
 */
function quux (foo) {

}
// Message: Duplicate @param "foo"

/**
 * @param foo
 * @param foo
 */
function quux (foo, bar) {

}
// Message: Duplicate @param "foo"

/**
 * @param foo
 * @param foo
 */
function quux (foo, foo) {

}
// Message: Duplicate @param "foo"

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param foo
 */
function quux (foo) {

}

/**
 * @param foo
 * @param bar
 */
function quux (foo, bar) {

}

/**
 * @param foo
 * @param bar
 */
function quux (foo, bar, baz) {

}

/**
 * @param foo
 * @param foo.foo
 * @param bar
 */
function quux (foo, bar) {

}

/**
 * @param args
 */
function quux (...args) {

}

/**
 * @param foo
 */
function quux ({a, b}) {

}

/**
 * @param foo
 */
function quux ({a, b} = {}) {

}

/**
 * @param foo
 */
function quux ([a, b] = []) {

}

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function assign (employees) {

};

Deconstructing Function Parameter

eslint-plugin-jsdoc does not validate names of parameters in function deconstruction, e.g.

/**
 * @param foo
 */
function quux ({
    a,
    b
}) {

}

{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 {string=} foo
 */
function quux (foo) {

}
// Message: Syntax should not be Google Closure Compiler style.

The following patterns are not considered problems:

/**
 * @param {string} [foo]
 */
function quux (foo) {

}

/**
 *
 */
function quux (foo) {

}

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
 */
function quux () {

}
// Message: Invalid JSDoc tag name "Param".

/**
 * @foo
 */
function quux () {

}
// Message: Invalid JSDoc tag name "foo".

/**
 * @arg foo
 */
function quux (foo) {

}
// Message: Invalid JSDoc tag (preference). Replace "arg" JSDoc tag with "param".

/**
 * @param foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg".

/**
 * @param foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"parameter"}}}
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "parameter".

/**
 * @bar foo
 */
function quux (foo) {

}
// Message: Invalid JSDoc tag name "bar".

/**
 * @baz @bar foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
// Message: Invalid JSDoc tag name "baz".

/**
 * @bar
 * @baz
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
// Message: Invalid JSDoc tag name "baz".

The following patterns are not considered problems:

/**
 * @param foo
 */
function quux (foo) {

}

/**
 * @memberof! foo
 */
function quux (foo) {

}

/**
 * @arg foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}

/**
 * @bar foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}

/**
 * @baz @bar foo
 */
function quux (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
 */
function quux (foo) {}

check-types

Reports invalid types.

By default, ensures that case of native types is the same as in this list:

undefined
null
boolean
number
string
object
Array
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.

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.

new String('lard') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
'lard' // "lard"
new String('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
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

The following patterns are considered problems:

/**
 * @param {Number} foo
 */
function quux (foo) {

}
// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number".

/**
 * @arg {Number} foo
 */
function quux (foo) {

}
// Message: Invalid JSDoc @arg "foo" type "Number"; prefer: "number".

/**
 * @returns {Number} foo
 * @throws {Number} foo
 */
function quux () {

}
// Message: Invalid JSDoc @returns type "Number"; prefer: "number".

/**
 * @param {(Number|string|Boolean)=} foo
 */
function quux (foo, bar, baz) {

}
// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number".

/**
 * @param {Array<Number|String>} foo
 */
function quux (foo, bar, baz) {

}
// Message: Invalid JSDoc @param "foo" type "Number"; prefer: "number".

/**
 * @param {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}
// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc".

/**
 * @param {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":{"replacement":"Abc"},"string":"Str"}}}
// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc".

/**
 * @param {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"; prefer: \"{{preferredType}}\".","replacement":"Abc"},"string":"Str"}}}
// Message: Messed up JSDoc @param "foo" type "abc"; prefer: "Abc".

/**
 * @param {abc} foo
 * @param {cde} bar
 * @param {object} baz
 */
function qux(foo, bar, baz) {
}
// 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 {abc} foo
 */
function qux(foo) {
}
// 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 {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":{"message":"Messed up JSDoc @{{tagName}}{{tagValue}} type \"{{badType}}\"."},"string":"Str"}}}
// Message: Messed up JSDoc @param "foo" type "abc".

/**
 * @param {abc} foo
 * @param {Number} bar
 */
function qux(foo, bar) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}
// Options: [{"noDefaults":true}]
// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc".

/**
 * @param {abc} foo
 * @param {Number} bar
 */
function qux(foo, bar) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}
// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc".

/**
 * @param {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":false,"string":"Str"}}}
// Message: Invalid JSDoc @param "foo" type "abc".

/**
 * @param {abc} foo
 */
function qux(foo) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":false}}}
// Message: Invalid JSDoc @param "foo" type "abc".

/**
 * @param {*} baz
 */
function qux(baz) {
}
// Settings: {"jsdoc":{"preferredTypes":{"*":false,"abc":"Abc","string":"Str"}}}
// Message: Invalid JSDoc @param "baz" type "*".

/**
 * @param {*} baz
 */
function qux(baz) {
}
// Settings: {"jsdoc":{"preferredTypes":{"*":"aaa","abc":"Abc","string":"Str"}}}
// Message: Invalid JSDoc @param "baz" type "*"; prefer: "aaa".

/**
 * @param {abc} foo
 * @param {Number} bar
 */
function qux(foo, bar) {
}
// Settings: {"jsdoc":{"preferredTypes":{"abc":"Abc","string":"Str"}}}
// Message: Invalid JSDoc @param "foo" type "abc"; prefer: "Abc".

The following patterns are not considered problems:

/**
 * @param {number} foo
 * @param {Bar} bar
 * @param {*} baz
 */
function quux (foo, bar, baz) {

}

/**
 * @arg {number} foo
 * @arg {Bar} bar
 * @arg {*} baz
 */
function quux (foo, bar, baz) {

}

/**
 * @param {(number|string|boolean)=} foo
 */
function quux (foo, bar, baz) {

}

/**
 * @param {typeof bar} foo
 */
function qux(foo) {
}

/**
 * @param {import('./foo').bar.baz} foo
 */
function qux(foo) {
}

/**
 * @param {(x: number, y: string) => string} foo
 */
function qux(foo) {
}

/**
 * @param {() => string} foo
 */
function qux(foo) {
}

/**
 * @returns {Number} foo
 * @throws {Number} foo
 */
function quux () {

}
// Options: [{"noDefaults":true}]

/**
 * @param {Object} foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"preferredTypes":{"object":"Object"}}}

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 {SomeClass}
 */
function quux () {

}
// Message: @implements used on a non-constructor function

The following patterns are not considered problems:

/**
 * @implements {SomeClass}
 * @class
 */
function quux () {

}

/**
 * @implements {SomeClass}
 * @constructor
 */
function quux () {

}

/**
 *
 */
class quux {
  /**
   * @implements {SomeClass}
   */
  constructor () {

  }
}

/**
 *
 */
function quux () {

}

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.
 */
function quux () {

}
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo)
 */
function quux () {

}
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * тест.
 */
function quux () {

}
// Options: [{"matchDescription":"[А-Я]+."}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo
 */
function quux () {

}
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo.
 *
 * @param foo foo.
 */
function quux (foo) {

}
// Options: [{"tags":{"param":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo.
 *
 * @param foo bar
 */
function quux (foo) {

}
// Options: [{"tags":{"param":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * {@see Foo.bar} buz
 */
function quux (foo) {

}
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo.
 *
 * @returns {number} foo
 */
function quux (foo) {

}
// Options: [{"tags":{"returns":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Foo.
 *
 * @returns foo.
 */
function quux (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.
 */
function longDescription (foo) {

}
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * @arg {number} foo - Foo
 */
function quux (foo) {

}
// Options: [{"tags":{"arg":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * @argument {number} foo - Foo
 */
function quux (foo) {

}
// Options: [{"tags":{"argument":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * @return {number} foo
 */
function quux (foo) {

}
// Options: [{"tags":{"return":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * Returns bar.
 *
 * @return {number} bar
 */
function quux (foo) {

}
// Options: [{"tags":{"return":true}}]
// Message: JSDoc description does not satisfy the regex pattern.

/**
 * @param notRet
 * @returns Тест.
 */
function quux () {

}
// Options: [{"tags":{"param":"[А-Я]+."}}]
// Message: JSDoc description does not satisfy the regex pattern.

The following patterns are not considered problems:

/**
 * @param foo - Foo.
 */
function quux () {

}
// Options: [{"tags":{"param":true}}]

/**
 * Foo.
 */
function quux () {

}

/**
 * Foo.
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * Bar.
 */
function quux () {

}

/**
 * Тест.
 */
function quux () {

}
// Options: [{"matchDescription":"[А-Я]+."}]

/**
 * @param notRet
 * @returns Тест.
 */
function quux () {

}
// Options: [{"tags":{"returns":"[А-Я]+."}}]

/**
 * Foo
 * bar.
 */
function quux () {

}

/**
 * @returns Foo bar.
 */
function quux () {

}
// Options: [{"tags":{"returns":true}}]

/**
 * Foo. {@see Math.sin}.
 */
function quux () {

}

/**
 * Foo {@see Math.sin} bar.
 */
function quux () {

}

/**
 * Foo?
 *
 * Bar!
 *
 * Baz:
 *   1. Foo.
 *   2. Bar.
 */
function quux () {

}

/**
 * Hello:
 * World.
 */
function quux () {

}

/**
 * Hello: world.
 */
function quux () {

}

/**
 * Foo
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * foo.
 */
function quux () {

}

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
 */
function quux () {

}
// Options: ["always"]
// Message: There must be a newline after the description of the JSDoc block.

/**
 * Bar.
 *
 * Bar.
 *
 * @bar
 */
function quux () {

}
// Options: ["never"]
// Message: There must be no newline after the description of the JSDoc block.

The following patterns are not considered problems:

/**
 * Foo.
 */
function quux () {

}
// Options: ["always"]

/**
 * Bar.
 */
function quux () {

}
// Options: ["never"]

/**
 * Foo.
 *
 * @foo
 */
function quux () {

}
// Options: ["always"]

/**
 * Bar.
 * @bar
 */
function quux () {

}
// 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 {number} foo
 */
function quux (foo) {

}
// Message: Types are not permitted on @param.

/**
 * @returns {number}
 */
function quux () {

}
// Message: Types are not permitted on @returns.

The following patterns are not considered problems:

/**
 * @param foo
 */
function quux (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
• number, NaN, Infinity
• any, *
• Array, Object, RegExp, Date, Function

Options

An option object may have the following keys:

• preferredTypesDefined - If this option is set to true and preferred types are indicated within settings.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

The following patterns are considered problems:

/**
 * @param {strnig} foo - Bar.
 */
function quux(foo) {

}
// Message: The type 'strnig' is undefined.

/**
* @param {MyType} foo - Bar.
* @param {HisType} bar - Foo.
*/
function quux(foo, bar) {

}
// Options: [{"definedTypes":["MyType"]}]
// Message: The type 'HisType' is undefined.

/**
  * @param {MyType} foo - Bar.
  * @param {HisType} bar - Foo.
  * @param {HerType} baz - Foo.
  */
function quux(foo, bar, baz) {

}
// Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType"}}}}
// Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
// Message: The type 'HisType' is undefined.

/**
  * @param {MyType} foo - Bar.
  * @param {HisType} bar - Foo.
  * @param {HerType} baz - Foo.
  */
function quux(foo, bar, baz) {

}
// 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 {string} foo - Bar.
 */
function quux(foo) {

}

/**
 * @param {Promise} foo - Bar.
 */
function quux(foo) {

}

class MyClass {}

/**
 * @param {MyClass} foo - Bar.
 */
function quux(foo) {
  console.log(foo);
}

quux(0);

const MyType = require('my-library').MyType;

/**
 * @param {MyType} foo - Bar.
 */
  function quux(foo) {

}

const MyType = require('my-library').MyType;

/**
 * @param {MyType} foo - Bar.
 */
  function quux(foo) {

}

import {MyType} from 'my-library';

/**
 * @param {MyType} foo - Bar.
 * @param {Object<string, number>} foo
 * @param {Array<string>} baz
 */
  function quux(foo, bar, baz) {

}

/*globals MyType*/

/**
 * @param {MyType} foo - Bar.
 * @param {HisType} bar - Foo.
 */
  function quux(foo, bar) {

}

/**
 * @typedef {Object} hello
 * @property {string} a - a.
 */

/**
 * @param {hello} foo
 */
function quux(foo) {

}

/**
 * @param {Array<syntaxError} foo
 */
function quux(foo) {

}

/**
 * Callback test.
 *
 * @callback addStuffCallback
 * @param {String} sum - An test integer.
 */
/**
 * Test Eslint.
 *
 * @param {addStuffCallback} callback - A callback to run.
 */
function testFunction(callback) {
  callback();
}

/**
 *
 *
 */
function foo () {

}

/**
* @param {MyType} foo - Bar.
* @param {HisType} bar - Foo.
*/
function quux(foo, bar) {

}
// Options: [{"definedTypes":["MyType","HisType"]}]

/**
  * @param {MyType} foo - Bar.
  * @param {HisType} bar - Foo.
  * @param {HerType} baz - Foo.
  */
function quux(foo, bar, baz) {

}
// 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.
 */
function quux () {

}
// Message: Sentence should start with an uppercase character.

/**
 * Foo)
 */
function quux () {

}
// Message: Sentence must end with a period.

/**
 * Foo.
 *
 * foo.
 */
function quux () {

}
// Message: Sentence should start with an uppercase character.

/**
 * тест.
 */
function quux () {

}
// Message: Sentence should start with an uppercase character.

/**
 * Foo
 */
function quux () {

}
// Message: Sentence must end with a period.

/**
 * Foo
 * Bar.
 */
function quux () {

}
// Message: A line of text is started with an uppercase character, but preceding line does not end the sentence.

/**
 * Foo.
 *
 * @param foo foo.
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * Foo.
 *
 * @param foo bar
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * {@see Foo.bar} buz
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * Foo.
 *
 * @returns {number} foo
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * Foo.
 *
 * @returns foo.
 */
function quux (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.
 */
function longDescription (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * @arg {number} foo - Foo
 */
function quux (foo) {

}
// Message: Sentence must end with a period.

/**
 * @argument {number} foo - Foo
 */
function quux (foo) {

}
// Message: Sentence must end with a period.

/**
 * @return {number} foo
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

/**
 * Returns bar.
 *
 * @return {number} bar
 */
function quux (foo) {

}
// Message: Sentence should start with an uppercase character.

The following patterns are not considered problems:

/**
 * @param foo - Foo.
 */
function quux () {

}

/**
 * Foo.
 */
function quux () {

}

/**
 * Foo.
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * Bar.
 */
function quux () {

}

/**
 * Тест.
 */
function quux () {

}

/**
 * Foo
 * bar.
 */
function quux () {

}

/**
 * @returns Foo bar.
 */
function quux () {

}

/**
 * Foo. {@see Math.sin}.
 */
function quux () {

}

/**
 * Foo {@see Math.sin} bar.
 */
function quux () {

}

/**
 * Foo?
 *
 * Bar!
 *
 * Baz:
 *   1. Foo.
 *   2. Bar.
 */
function quux () {

}

/**
 * Hello:
 * World.
 */
function quux () {

}

/**
 * Hello: world.
 */
function quux () {

}

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 permit ArrowFunctionExpression, FunctionDeclaration, and FunctionExpression. Set this instead to true to have contexts override these.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression; others when contexts option enabled
Tags	description
Aliases	desc
Options	contexts, noDefaults

The following patterns are considered problems:

/**
 *
 */
function quux () {

}
// Message: Missing JSDoc @description declaration.

/**
 *
 */
class quux {

}
// Options: [{"contexts":"ClassDeclaration"}]
// Message: Missing JSDoc @description declaration.

/**
 *
 */
class quux {

}
// Options: [{"contexts":"ClassDeclaration","noDefaults":true}]
// Message: Missing JSDoc @description declaration.

/**
 *
 */
class quux {

}
// Options: [{"contexts":["ClassDeclaration"]}]
// Message: Missing JSDoc @description declaration.

/**
 * @description
 */
function quux () {

}
// Message: Missing JSDoc @description description.

The following patterns are not considered problems:

/**
 * @description
 * // arbitrary description content
 */
function quux () {

}

/**
 * @description
 * quux(); // does something useful
 */
function quux () {

}

/**
 * @description <caption>Valid usage</caption>
 * quux(); // does something useful
 *
 * @description <caption>Invalid usage</caption>
 * quux('random unwanted arg'); // results in an error
 */
function quux () {

}

/**
 *
 */
class quux {

}

/**
 *
 */
function quux () {

}
// 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:

/**
 *
 */
function quux () {

}
// Message: Missing JSDoc @example declaration.

/**
 * @example
 */
function quux () {

}
// Message: Missing JSDoc @example description.

/**
 * @constructor
 */
function quux () {

}
// Message: Missing JSDoc @example declaration.

/**
 * @constructor
 * @example
 */
function quux () {

}
// Message: Missing JSDoc @example description.

The following patterns are not considered problems:

/**
 * @example
 * // arbitrary example content
 */
function quux () {

}

/**
 * @example
 * quux(); // does something useful
 */
function quux () {

}

/**
 * @example <caption>Valid usage</caption>
 * quux(); // does something useful
 *
 * @example <caption>Invalid usage</caption>
 * quux('random unwanted arg'); // results in an error
 */
function quux () {

}

/**
 * @constructor
 */
function quux () {

}
// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}}

/**
 * @constructor
 * @example
 */
function quux () {

}
// Settings: {"jsdoc":{"avoidExampleOnConstructors":true}}

/**
 * @inheritdoc
 */
function quux () {

}

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.
 */
function quux () {

}
// Options: ["always"]
// Message: There must be a hyphen before @param description.

/**
 * @param foo - Foo.
 */
function quux () {

}
// Options: ["never"]
// Message: There must be no hyphen before @param description.

The following patterns are not considered problems:

/**
 * @param foo - Foo.
 */
function quux () {

}
// Options: ["always"]

/**
 * @param foo Foo.
 */
function quux () {

}
// 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:

function quux (foo) {

}
// Message: Missing JSDoc comment.

function myFunction() {}
// Message: Missing JSDoc comment.

/**
 * Description for A.
 */
class A {
   constructor(xs) {
        this.a = xs;
   }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]
// Message: Missing JSDoc comment.

class A {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]
// Message: Missing JSDoc comment.

class A extends B {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]
// Message: Missing JSDoc comment.

export class A extends B {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]
// Message: Missing JSDoc comment.

export default class A extends B {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]
// Message: Missing JSDoc comment.

var myFunction = () => {}
// Options: [{"require":{"ArrowFunctionExpression":true}}]
// Message: Missing JSDoc comment.

var myFunction = () => () => {}
// Options: [{"require":{"ArrowFunctionExpression":true}}]
// Message: Missing JSDoc comment.

var foo = function() {}
// Options: [{"require":{"FunctionExpression":true}}]
// Message: Missing JSDoc comment.

const foo = {bar() {}}
// Options: [{"require":{"FunctionExpression":true}}]
// Message: Missing JSDoc comment.

var foo = {bar: function() {}}
// Options: [{"require":{"FunctionExpression":true}}]
// Message: Missing JSDoc comment.

function foo (abc) {}
// Settings: {"jsdoc":{"exemptEmptyFunctions":false}}
// Message: Missing JSDoc comment.

function foo () {
  return true;
}
// Settings: {"jsdoc":{"exemptEmptyFunctions":false}}
// Message: Missing JSDoc comment.

The following patterns are not considered problems:

var array = [1,2,3];
array.forEach(function() {});

/**
 * @class MyClass
 **/
function MyClass() {}

/**
 Function doing something
 */
function myFunction() {}
/**
 Function doing something
 */
var myFunction = function() {};
/**
 Function doing something
 */
Object.myFunction = function () {};
var obj = {
   /**
    *  Function doing something
    **/
    myFunction: function () {} };

/**
 @func myFunction
 */
function myFunction() {}
/**
 @method myFunction
 */
function myFunction() {}
/**
 @function myFunction
 */
function myFunction() {}

/**
 @func myFunction
 */
var myFunction = function () {}
/**
 @method myFunction
 */
var myFunction = function () {}
/**
 @function myFunction
 */
var myFunction = function () {}

/**
 @func myFunction
 */
Object.myFunction = function() {}
/**
 @method myFunction
 */
Object.myFunction = function() {}
/**
 @function myFunction
 */
Object.myFunction = function() {}
(function(){})();

var object = {
  /**
   *  @func myFunction - Some function
   */
  myFunction: function() {} }
var object = {
  /**
   *  @method myFunction - Some function
   */
  myFunction: function() {} }
var object = {
  /**
   *  @function myFunction - Some function
   */
  myFunction: function() {} }

var array = [1,2,3];
array.filter(function() {});
Object.keys(this.options.rules || {}).forEach(function(name) {}.bind(this));
var object = { name: 'key'};
Object.keys(object).forEach(function() {})

function myFunction() {}
// Options: [{"require":{"ClassDeclaration":true,"FunctionDeclaration":false,"MethodDefinition":true}}]

var myFunction = function() {}
// Options: [{"require":{"ClassDeclaration":true,"FunctionDeclaration":false,"MethodDefinition":true}}]

/**
 * Description for A.
 */
class A {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]

/**
 * Description for A.
 */
class App extends Component {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]

/**
 * Description for A.
 */
export default class App extends Component {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]

/**
 * Description for A.
 */
export class App extends Component {
    /**
     * Description for constructor.
     * @param {object[]} xs - xs
     */
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":true,"MethodDefinition":true}}]

class A {
    constructor(xs) {
        this.a = xs;
    }
}
// Options: [{"require":{"ClassDeclaration":false,"MethodDefinition":false}}]

/**
 Function doing something
*/
var myFunction = () => {}
// Options: [{"require":{"ArrowFunctionExpression":true}}]

/**
 Function doing something
*/
var myFunction = () => () => {}
// Options: [{"require":{"ArrowFunctionExpression":true}}]

setTimeout(() => {}, 10);
// Options: [{"require":{"ArrowFunctionExpression":true}}]

/**
JSDoc Block
*/
var foo = function() {}
// Options: [{"require":{"FunctionExpression":true}}]

const foo = {/**
JSDoc Block
*/
bar() {}}
// Options: [{"require":{"FunctionExpression":true}}]

var foo = {/**
JSDoc Block
*/
bar: function() {}}
// Options: [{"require":{"FunctionExpression":true}}]

var foo = { [function() {}]: 1 };
// Options: [{"require":{"FunctionExpression":true}}]

function foo () {}
// Settings: {"jsdoc":{"exemptEmptyFunctions":true}}

function foo () {
  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
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" description.

/**
 * @arg foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
// Message: Missing JSDoc @arg "foo" description.

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param foo Foo.
 */
function quux (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.

JSDoc

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param
Aliases	arg, argument

The following patterns are considered problems:

/**
 * @param
 */
function quux (foo) {

}
// Message: There must be an identifier after @param type.

/**
 * @param {string}
 */
function quux (foo) {

}
// Message: There must be an identifier after @param tag.

The following patterns are not considered problems:

/**
 * @param foo
 */
function quux (foo) {

}

/**
 * @param {string} foo
 */
function quux (foo) {

}

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
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" type.

/**
 * @arg foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
// Message: Missing JSDoc @arg "foo" type.

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param {number} foo
 */
function quux (foo) {

}

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:

/**
 *
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" declaration.

/**
 *
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
// Message: Missing JSDoc @arg "foo" declaration.

/**
 * @param foo
 */
function quux (foo, bar) {

}
// Message: Missing JSDoc @param "bar" declaration.

/**
 * @override
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @implements
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @augments
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @extends
 */
function quux (foo) {

}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @override
 */
class A {
  /**
    *
    */
  quux (foo) {

  }
}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @implements
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @augments
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Message: Missing JSDoc @param "foo" declaration.

/**
 * @extends
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Message: Missing JSDoc @param "foo" declaration.

The following patterns are not considered problems:

/**
 * @param foo
 */
function quux (foo) {

}

/**
 * @inheritdoc
 */
function quux (foo) {

}

/**
 * @arg foo
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}

/**
 * @override
 * @param foo
 */
function quux (foo) {

}

/**
 * @override
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}

/**
 * @implements
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}

/**
 * @implements
 * @param foo
 */
function quux (foo) {

}

/**
 * @augments
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}

/**
 * @augments
 * @param foo
 */
function quux (foo) {

}

/**
 * @extends
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}

/**
 * @extends
 * @param foo
 */
function quux (foo) {

}

/**
 * @override
 */
class A {
  /**
  * @param foo
  */
  quux (foo) {

  }
}

/**
 * @override
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}

/**
 * @implements
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}

/**
 * @implements
 */
class A {
  /**
   * @param foo
   */
  quux (foo) {

  }
}

/**
 * @augments
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}

/**
 * @augments
 */
class A {
  /**
   * @param foo
   */
  quux (foo) {

  }
}

/**
 * @extends
 */
class A {
  /**
   *
   */
  quux (foo) {

  }
}
// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}

/**
 * @extends
 */
class A {
  /**
   * @param foo
   */
  quux (foo) {

  }
}

/**
 * @private
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"ignorePrivate":true}}

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
 */
function quux (foo) {

}
// Message: JSDoc @returns declaration present but return expression not available in function.

/**
 * @return
 */
function quux (foo) {

}
// 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 {undefined} Foo.
 * @returns {String} Foo.
 */
function quux () {

  return foo;
}
// Message: Found more than one @returns declaration.

const language = {
  /**
   * @param {string} name
   * @returns {string}
   */
  get name() {
    this._name = name;
  }
}
// Message: JSDoc @returns declaration present but return expression not available in function.

The following patterns are not considered problems:

/**
 * @returns Foo.
 */
function quux () {

  return foo;
}

/**
 * @returns {string} Foo.
 */
function quux () {

  return foo;
}

/**
 * @returns {string} Foo.
 */
function quux () {

  return foo;
}

/**
 *
 */
function quux () {
}

/**
 * @returns {*} Foo.
 */
const quux = () => foo;

/**
 * @returns {undefined} Foo.
 */
function quux () {}

/**
 * @returns { void } Foo.
 */
function quux () {}

/**
 * @returns {Promise<void>}
 */
async function quux() {}

/**
 * @returns {Promise<void>}
 */
const quux = async function () {}

/**
 * @returns {Promise<void>}
 */
const quux = async () => {}

/**
 * @returns Foo.
 * @abstract
 */
function quux () {
  throw new Error('must be implemented by subclass!');
}

/**
 * @returns Foo.
 * @virtual
 */
function quux () {
  throw new Error('must be implemented by subclass!');
}

/**
 * @returns Foo.
 * @constructor
 */
function quux () {
}

/**
 * @returns {undefined} Foo.
 */
function quux () {
}

/**
 * @returns {void} Foo.
 */
function quux () {
}

/**
 * @returns {void} Foo.
 */
function quux () {
  return undefined;
}

/**
 * @returns {void} Foo.
 */
function quux () {
  return;
}

/**
 *
 */
function quux () {
  return undefined;
}

/**
 *
 */
function quux () {
  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
 */
function quux (foo) {

}
// Message: Missing JSDoc @returns description.

/**
 * @return
 */
function quux (foo) {

}
// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
// Message: Missing JSDoc @return description.

The following patterns are not considered problems:

/**
 *
 */
function quux () {

}

/**
 * @returns Foo.
 */
function quux () {

}

/**
 * @returns {undefined}
 */
function quux () {

}

/**
 * @returns {void}
 */
function quux () {

}

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
 */
function quux () {

}
// Message: Missing JSDoc @returns type.

/**
 * @returns Foo.
 */
function quux () {

}
// Message: Missing JSDoc @returns type.

/**
 * @return Foo.
 */
function quux () {

}
// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
// Message: Missing JSDoc @return type.

The following patterns are not considered problems:

/**
 * @returns {number}
 */
function quux () {

}

require-returns

Requires returns are documented.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	returns
Aliases	return
Settings	forceRequireReturn

The following patterns are considered problems:

/**
 *
 */
function quux (foo) {

  return foo;
}
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
const foo = () => ({
  bar: 'baz'
})
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
const foo = bar=>({ bar })
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
const foo = bar => bar.baz()
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
function quux (foo) {

  return foo;
}
// Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
// Message: Missing JSDoc @return declaration.

/**
 *
 */
async function quux() {}
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
const quux = async function () {}
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
const quux = async () => {}
// Message: Missing JSDoc @returns declaration.

/**
 *
 */
function quux () {
}
// Settings: {"jsdoc":{"forceRequireReturn":true}}
// Message: Missing JSDoc @returns declaration.

const language = {
  /**
   * @param {string} name
   */
  get name() {
    return this._name;
  }
}
// Message: Missing JSDoc @returns declaration.

The following patterns are not considered problems:

/**
 * @returns Foo.
 */
function quux () {

  return foo;
}

/**
 *
 */
function quux () {
}

/**
 *
 */
function quux (bar) {
  bar.filter(baz => {
    return baz.corge();
  })
}

/**
 * @returns Array
 */
function quux (bar) {
  return bar.filter(baz => {
    return baz.corge();
  })
}

/**
 * @returns Array
 */
const quux = (bar) => bar.filter(({ corge }) => corge())

/**
 * @inheritdoc
 */
function quux (foo) {
}

/**
 * @override
 */
function quux (foo) {
}

/**
 * @constructor
 */
function quux (foo) {
}

/**
 * @implements
 */
function quux (foo) {
}

/**
 * @override
 */
function quux (foo) {

  return foo;
}

/**
 * @class
 */
function quux (foo) {

}

/**
 * @constructor
 */
function quux (foo) {

}

/**
 * @returns {Object}
 */
function quux () {

  return {a: foo};
}

/**
 * @returns {Object}
 */
const quux = () => ({a: foo});

/**
 * @returns {Object}
 */
const quux = () => {
  return {a: foo}
};

/**
 * @returns {void}
 */
function quux () {
}

/**
 * @returns {void}
 */
const quux = () => {

}

/**
 * @returns {undefined}
 */
function quux () {
}

/**
 * @returns {undefined}
 */
const quux = () => {

}

/**
 *
 */
function quux () {
}

/**
 *
 */
const quux = () => {

}

class Foo {
  /**
   *
   */
  constructor () {
  }
}
// Settings: {"jsdoc":{"forceRequireReturn":true}}

const language = {
  /**
   * @param {string} name
   */
  set name(name) {
    this._name = name;
  }
}

/**
 * @returns {void}
 */
function quux () {
}
// Settings: {"jsdoc":{"forceRequireReturn":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:

1. Name(path)-defining tags requiring namepath: @external, @host, @name, @typedef
2. 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
3. Name(path)-pointing tags requiring namepath: @alias, @augments, @extends, @lends, @memberof, @memberof!, @mixes, @this
4. Name(path)-pointing tags (which may have value without namepath or their namepath can be expressed elsewhere on the block): @listens, @fires, @emits
5. 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 to false 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 an as between them.

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
 */
function quux() {

}
// Message: Syntax error in type: Array<string

/**
 * @borrows foo% as bar
 */
function quux() {

}
// Message: Syntax error in type: foo%

/**
 * @borrows foo as bar%
 */
function quux() {

}
// Message: Syntax error in type: bar%

/**
 * @borrows foo
 */
function quux() {

}
// Message: @borrows must have an "as" expression. Found ""

/**
 * @see foo%
 */
function quux() {

}
// Settings: {"jsdoc":{"checkSeesForNamepaths":true}}
// Message: Syntax error in type: foo%

/**
 * @alias module:abc#event:foo-bar
 */
function quux() {

}
// Message: Syntax error in type: module:abc#event:foo-bar

/**
 * @callback
 */
function quux() {

}
// Settings: {"jsdoc":{"allowEmptyNamepaths":false}}
// Message: Syntax error in type: 

The following patterns are not considered problems:

/**
 * @param {Array<string>} foo
 */
function quux() {

}

/**
 * @param {string} foo
 */
function quux() {

}

/**
 * @param foo
 */
function quux() {

}

/**
 * @borrows foo as bar
 */
function quux() {

}

/**
 * @see foo%
 */
function quux() {

}

/**
 * @alias module:namespace.SomeClass#event:ext_anevent
 */
function quux() {

}

/**
 * @callback
 */
function quux() {

}

/**
 * @class
 */
function quux() {

}

/**
 * @see {@link foo}
 */
function quux() {

}

/**
 *
 * @fires {module:namespace.SomeClass#event:ext_anevent}
 */
function quux() {

}