eslint-plugin-jsdoc
Advanced tools
The eslint-plugin-jsdoc package is a plugin for ESLint that provides linting rules for JSDoc comments. JSDoc is a markup language used to annotate JavaScript source code files. Using eslint-plugin-jsdoc, developers can ensure that their JSDoc comments are consistent and follow best practices.
Check alignment
Ensures that JSDoc blocks are aligned properly.
/* eslint jsdoc/check-alignment: "error" */
/**
* Function description.
*
* @param {string} name - The name of the person.
* @return {string} - The greeting message.
*/
function greet(name) {
return `Hello, ${name}!`;
}Check indentation
Ensures that JSDoc blocks have consistent indentation.
/* eslint jsdoc/check-indentation: "error" */
/**
* Function description.
*
* @param {string} name - The name of the person.
* @return {string} - The greeting message.
*/
function greet(name) {
return `Hello, ${name}!`;
}Check types
Validates JSDoc comments for type correctness.
/* eslint jsdoc/check-types: "error" */
/**
* Function description.
*
* @param {String} name - The name of the person.
* @return {String} - The greeting message.
*/
function greet(name) {
return `Hello, ${name}!`;
}Require JSDoc
Requires JSDoc comments for certain nodes in the code.
/* eslint jsdoc/require-jsdoc: "error" */
/**
* Function description.
*/
function greet(name) {
return `Hello, ${name}!`;
}TSDoc is a documentation comment format used for TypeScript source files. It is similar to JSDoc but tailored for the TypeScript language, providing a standardized way to document TypeScript APIs. Unlike eslint-plugin-jsdoc, TSDoc does not provide linting rules but focuses on the comment format itself.
The 'documentation' package is a documentation generator that uses JSDoc comments to produce documentation for JavaScript code. It is similar to eslint-plugin-jsdoc in that it processes JSDoc comments, but its primary purpose is to generate documentation rather than lint code.
TypeDoc is a documentation generator for TypeScript projects. It reads TypeScript source files and JSDoc comments to produce documentation. While eslint-plugin-jsdoc focuses on linting JSDoc comments, TypeDoc uses them to generate documentation websites or markdown files.
JSDoc linting rules for ESLint.
check-examplescheck-param-namescheck-tag-namescheck-typesnewline-after-descriptionno-undefined-typesrequire-description-complete-sentencerequire-descriptionrequire-examplerequire-hyphen-before-param-descriptionrequire-param-descriptionrequire-param-namerequire-param-typerequire-paramrequire-returns-descriptionrequire-returns-typerequire-returnsvalid-typesThis table maps the rules between eslint-plugin-jsdoc and jscs-jsdoc.
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
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-examples": 1,
"jsdoc/check-param-names": 1,
"jsdoc/check-tag-names": 1,
"jsdoc/check-types": 1,
"jsdoc/newline-after-description": 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-param": 1,
"jsdoc/require-param-description": 1,
"jsdoc/require-param-name": 1,
"jsdoc/require-param-type": 1,
"jsdoc/require-returns": 1,
"jsdoc/require-returns-description": 1,
"jsdoc/require-returns-type": 1,
"jsdoc/valid-types": 1
}
}
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"
}
}
}
}
Use settings.jsdoc.additionalTagNames to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
{
"rules": {},
"settings": {
"jsdoc": {
"additionalTagNames": {
"customTags": ["define", "extends", "record"]
}
}
}
}
@override Without Accompanying @param TagsUse 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 tagsettings.jsdoc.allowImplementsWithoutParam - Enables behavior with
@implements tagsettings.jsdoc.allowAugmentsExtendsWithoutParam - Enables behavior with
@augments tag or its synonym @extendsThe format of the configuration is as follows:
{
"rules": {},
"settings": {
"jsdoc": {
"allowOverrideWithoutParam": true,
"allowImplementsWithoutParam": true,
"allowAugmentsExtendsWithoutParam": true
}
}
}
check-examplesThe 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 @exampleJSDoc 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 defaultsFinally, 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.noDefaultExampleRules is Set to trueeol-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 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 infonode/no-missing-import - See import/no-unresolvednode/no-missing-require - See import/no-unresolvedcheck-examplesEnsures that (JavaScript) examples within JSDoc adhere to ESLint rules.
Works in conjunction with the following settings:
captionRequiredexampleCodeRegexrejectExampleCodeRegexallowInlineConfig - Defaults to truenoDefaultExampleRulesmatchingFileNameconfigFileeslintrcForExamples - Defaults to truebaseConfigreportUnusedDisableDirectives - Defaults to trueInline 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, FunctionDeclaration, FunctionExpression |
| Tags | param |
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 ```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 (semi): Extra semicolon.
/**
* @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-param-namesEnsures 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.
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) {
};
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-tag-namesReports invalid block tag names.
Valid JSDoc 3 Block Tags are:
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
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
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | N/A |
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".
/**
* @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) {
}
/**
* @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
* @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-typesReports invalid types.
Ensures that case of native types is the same as in this list:
boolean
number
string
Object
Array
Date
RegExp
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.
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.
| type name | typeof | check-types | testcase |
|---|---|---|---|
| Object | object | Object | ({}) instanceof Object -> true |
| Array | object | Array | ([]) instanceof Array -> true |
| Date | object | Date | (new Date()) instanceof Date -> true |
| RegExp | object | RegExp | (new RegExp(/.+/)) instanceof RegExp -> true |
| 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, member, module, namespace, param, property, returns, throws, type, typedef |
The following patterns are considered problems:
/**
* @param {Number} foo
*/
function quux (foo) {
}
// Message: Invalid JSDoc @param "foo" type "Number".
/**
* @arg {Number} foo
*/
function quux (foo) {
}
// Message: Invalid JSDoc @arg "foo" type "Number".
/**
* @param {(Number|string|Boolean)=} foo
*/
function quux (foo, bar, baz) {
}
// Message: Invalid JSDoc @param "foo" type "Number".
/**
* @param {Array<Number|String>} foo
*/
function quux (foo, bar, baz) {
}
// Message: Invalid JSDoc @param "foo" type "Number".
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) {
}
newline-after-descriptionEnforces 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-undefined-typesChecks 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.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param, returns |
The following patterns are considered problems:
/**
* @param {strnig} foo - Bar.
*/
function quux(foo) {
}
// Message: The type 'strnig' is undefined.
The following patterns are not considered problems:
/**
* @param {string} 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) {
}
import {MyType} from 'my-library';
/**
* @param {MyType} foo - Bar.
* @param {Object<string, number>} foo
* @param {Array<string>} baz
*/
function quux(foo, bar, baz) {
}
/*global 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) {
}
require-description-complete-sentenceRequires that block description and tag description are written in complete sentences, i.e.,
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param, returns |
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-descriptionRequires that all functions have a description.
@description tag.| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | class, example |
The following patterns are considered problems:
/**
*
*/
function quux () {
}
// 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 () {
}
require-exampleRequires that all functions have examples.
@example tags.| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | example |
The following patterns are considered problems:
/**
*
*/
function quux () {
}
// Message: Missing JSDoc @example declaration.
/**
* @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 () {
}
require-hyphen-before-param-descriptionRequires a hyphen before the @param description.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param |
The following patterns are considered problems:
/**
* @param foo Foo.
*/
function quux () {
}
// Message: There must be a hyphen before @param description.
The following patterns are not considered problems:
/**
* @param foo - Foo.
*/
function quux () {
}
require-param-descriptionRequires that @param tag has description value.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param |
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-nameRequires that all function parameters have name.
The
@paramtag 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 |
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-typeRequires that @param tag has type value.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param |
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-paramRequires that all function parameters are documented.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param |
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) {
}
}
require-returns-descriptionRequires that @returns tag has description value.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | returns |
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 () {
}
require-returns-typeRequires that @returns tag has type value.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | returns |
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-returnsRequires returns are documented.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | returns |
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) {
}
}
valid-typesRequires all types to be valid JSDoc or Closure compiler types without syntax errors.
| Context | ArrowFunctionExpression, FunctionDeclaration, FunctionExpression |
| Tags | param, returns |
The following patterns are considered problems:
/**
* @param {Array<string} foo
*/
function quux() {
}
// Message: Syntax error in type: Array<string
The following patterns are not considered problems:
/**
* @param {Array<string>} foo
*/
function quux() {
}
/**
* @param {string} foo
*/
function quux() {
}
/**
* @param foo
*/
function quux() {
}
FAQs
JSDoc linting rules for ESLint.
The npm package eslint-plugin-jsdoc receives a total of 2,353,056 weekly downloads. As such, eslint-plugin-jsdoc popularity was classified as popular.
We found that eslint-plugin-jsdoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.