File Network.test.js
has 767 lines of code (exceeds 250 allowed). Consider refactoring. Open
/**
*
* Useful during debugging
* =======================
*
Function createSampleNetwork
has 40 lines of code (exceeds 25 allowed). Consider refactoring. Open
function createSampleNetwork(options) {
var NumInitialNodes = 8;
var NumInitialEdges = 6;
var nodes = new vis.DataSet([
Function merge
has a Cognitive Complexity of 13 (exceeds 5 allowed). Consider refactoring. Open
function merge (a, b) {
if (!a) {
a = {};
}
- Read upRead up
Cognitive Complexity
Cognitive Complexity is a measure of how difficult a unit of code is to intuitively understand. Unlike Cyclomatic Complexity, which determines how difficult your code will be to test, Cognitive Complexity tells you how difficult your code will be to read and comprehend.
A method's cognitive complexity is based on a few simple rules:
- Code is not considered more complex when it uses shorthand that the language provides for collapsing multiple statements into one
- Code is considered more complex for each "break in the linear flow of the code"
- Code is considered more complex when "flow breaking structures are nested"
Further reading
Function createOutlierGraph
has 28 lines of code (exceeds 25 allowed). Consider refactoring. Open
function createOutlierGraph() {
// create an array with nodes
var nodes = new vis.DataSet([
{id: 1, label: '1', group:'Group1'},
{id: 2, label: '2', group:'Group2'},
Function checkFontProperties
has 26 lines of code (exceeds 25 allowed). Consider refactoring. Open
function checkFontProperties(fontItem, checkStrict = true) {
var knownProperties = [
'color',
'size',
'face',
Function checkFontProperties
has a Cognitive Complexity of 7 (exceeds 5 allowed). Consider refactoring. Open
function checkFontProperties(fontItem, checkStrict = true) {
var knownProperties = [
'color',
'size',
'face',
- Read upRead up
Cognitive Complexity
Cognitive Complexity is a measure of how difficult a unit of code is to intuitively understand. Unlike Cyclomatic Complexity, which determines how difficult your code will be to test, Cognitive Complexity tells you how difficult your code will be to read and comprehend.
A method's cognitive complexity is based on a few simple rules:
- Code is not considered more complex when it uses shorthand that the language provides for collapsing multiple statements into one
- Code is considered more complex for each "break in the linear flow of the code"
- Code is considered more complex when "flow breaking structures are nested"
Further reading
'Validator' is assigned a value but never used. Open
var Validator = require("./../lib/shared/Validator").default;
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'hovering' is defined but never used. Open
edge: function(value, id, selected, hovering) {},
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'data' is assigned a value but never used. Open
var [network, data] = createSampleNetwork();
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'nodes' is not defined. Open
nodes: new vis.DataSet(nodes),
- Read upRead up
- Exclude checks
Disallow Undeclared Variables (no-undef)
This rule can help you locate potential ReferenceErrors resulting from misspellings of variable and parameter names, or accidental implicit globals (for example, from forgetting the var
keyword in a for
loop initializer).
Rule Details
Any reference to an undeclared variable causes a warning, unless the variable is explicitly mentioned in a /*global ...*/
comment.
Examples of incorrect code for this rule:
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
Examples of correct code for this rule with global
declaration:
/*global someFunction b:true*/
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
The b:true
syntax in /*global */
indicates that assignment to b
is correct.
Examples of incorrect code for this rule with global
declaration:
/*global b*/
/*eslint no-undef: "error"*/
b = 10;
By default, variables declared in /*global */
are read-only, therefore assignment is incorrect.
Options
-
typeof
set to true will warn for variables used inside typeof check (Default false).
typeof
Examples of correct code for the default { "typeof": false }
option:
/*eslint no-undef: "error"*/
if (typeof UndefinedIdentifier === "undefined") {
// do something ...
}
You can use this option if you want to prevent typeof
check on a variable which has not been declared.
Examples of incorrect code for the { "typeof": true }
option:
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Examples of correct code for the { "typeof": true }
option with global
declaration:
/*global a*/
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Environments
For convenience, ESLint provides shortcuts that pre-define global variables exposed by popular libraries and runtime environments. This rule supports these environments, as listed in Specifying Environments. A few examples are given below.
browser
Examples of correct code for this rule with browser
environment:
/*eslint no-undef: "error"*/
/*eslint-env browser*/
setTimeout(function() {
alert("Hello");
});
node
Examples of correct code for this rule with node
environment:
/*eslint no-undef: "error"*/
/*eslint-env node*/
var fs = require("fs");
module.exports = function() {
console.log(fs);
};
When Not To Use It
If explicit declaration of global variables is not to your taste.
Compatibility
This rule provides compatibility with treatment of global variables in JSHint and JSLint. Source: http://eslint.org/docs/rules/
'Network' is assigned a value but never used. Open
var Network = vis.network;
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for (var n in list) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for (var n in knownProperties) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
'numEdges' is assigned a value but never used. Open
var [network, data, numNodes, numEdges] = createSampleNetwork(options);
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'numNodes' is already defined. Open
var [network, data, numNodes, numEdges] = createSampleNetwork();
- Read upRead up
- Exclude checks
disallow variable redeclaration (no-redeclare)
In JavaScript, it's possible to redeclare the same variable name using var
. This can lead to confusion as to where the variable is actually declared and initialized.
Rule Details
This rule is aimed at eliminating variables that have multiple declarations in the same scope.
Examples of incorrect code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
var a = 10;
Examples of correct code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
// ...
a = 10;
Options
This rule takes one optional argument, an object with a boolean property "builtinGlobals"
. It defaults to false
.
If set to true
, this rule also checks redeclaration of built-in globals, such as Object
, Array
, Number
...
builtinGlobals
Examples of incorrect code for the { "builtinGlobals": true }
option:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
var Object = 0;
Examples of incorrect code for the { "builtinGlobals": true }
option and the browser
environment:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
/*eslint-env browser*/
var top = 0;
The browser
environment has many built-in global variables (for example, top
). Some of built-in global variables cannot be redeclared.
Source: http://eslint.org/docs/rules/
Unnecessary semicolon. Open
};
- Read upRead up
- Exclude checks
disallow unnecessary semicolons (no-extra-semi)
Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
Rule Details
This rule disallows unnecessary semicolons.
Examples of incorrect code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;;
function foo() {
// code
};
Examples of correct code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;
var foo = function() {
// code
};
When Not To Use It
If you intentionally use extra semicolons then you can disable this rule.
Related Rules
- [semi](semi.md)
- [semi-spacing](semi-spacing.md) Source: http://eslint.org/docs/rules/
'prop' is already defined. Open
var prop = knownProperties[n];
- Read upRead up
- Exclude checks
disallow variable redeclaration (no-redeclare)
In JavaScript, it's possible to redeclare the same variable name using var
. This can lead to confusion as to where the variable is actually declared and initialized.
Rule Details
This rule is aimed at eliminating variables that have multiple declarations in the same scope.
Examples of incorrect code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
var a = 10;
Examples of correct code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
// ...
a = 10;
Options
This rule takes one optional argument, an object with a boolean property "builtinGlobals"
. It defaults to false
.
If set to true
, this rule also checks redeclaration of built-in globals, such as Object
, Array
, Number
...
builtinGlobals
Examples of incorrect code for the { "builtinGlobals": true }
option:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
var Object = 0;
Examples of incorrect code for the { "builtinGlobals": true }
option and the browser
environment:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
/*eslint-env browser*/
var top = 0;
The browser
environment has many built-in global variables (for example, top
). Some of built-in global variables cannot be redeclared.
Source: http://eslint.org/docs/rules/
'n' is defined but never used. Open
var joinNone_ = function(n) { return false ; }
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
Unnecessary semicolon. Open
};
- Read upRead up
- Exclude checks
disallow unnecessary semicolons (no-extra-semi)
Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
Rule Details
This rule disallows unnecessary semicolons.
Examples of incorrect code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;;
function foo() {
// code
};
Examples of correct code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;
var foo = function() {
// code
};
When Not To Use It
If you intentionally use extra semicolons then you can disable this rule.
Related Rules
- [semi](semi.md)
- [semi-spacing](semi-spacing.md) Source: http://eslint.org/docs/rules/
'numNodes' is assigned a value but never used. Open
var [network, data, numNodes, numEdges] = createSampleNetwork({});
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
Unnecessary semicolon. Open
};
- Read upRead up
- Exclude checks
disallow unnecessary semicolons (no-extra-semi)
Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
Rule Details
This rule disallows unnecessary semicolons.
Examples of incorrect code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;;
function foo() {
// code
};
Examples of correct code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;
var foo = function() {
// code
};
When Not To Use It
If you intentionally use extra semicolons then you can disable this rule.
Related Rules
- [semi](semi.md)
- [semi-spacing](semi-spacing.md) Source: http://eslint.org/docs/rules/
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for(var n in network.body.nodes) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
'joinAll_' is assigned a value but never used. Open
var joinAll_ = function(n) { return true ; }
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
Unnecessary semicolon. Open
};
- Read upRead up
- Exclude checks
disallow unnecessary semicolons (no-extra-semi)
Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
Rule Details
This rule disallows unnecessary semicolons.
Examples of incorrect code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;;
function foo() {
// code
};
Examples of correct code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;
var foo = function() {
// code
};
When Not To Use It
If you intentionally use extra semicolons then you can disable this rule.
Related Rules
- [semi](semi.md)
- [semi-spacing](semi-spacing.md) Source: http://eslint.org/docs/rules/
Unnecessary semicolon. Open
};
- Read upRead up
- Exclude checks
disallow unnecessary semicolons (no-extra-semi)
Typing mistakes and misunderstandings about where semicolons are required can lead to semicolons that are unnecessary. While not technically an error, extra semicolons can cause confusion when reading code.
Rule Details
This rule disallows unnecessary semicolons.
Examples of incorrect code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;;
function foo() {
// code
};
Examples of correct code for this rule:
/*eslint no-extra-semi: "error"*/
var x = 5;
var foo = function() {
// code
};
When Not To Use It
If you intentionally use extra semicolons then you can disable this rule.
Related Rules
- [semi](semi.md)
- [semi-spacing](semi-spacing.md) Source: http://eslint.org/docs/rules/
'hovering' is defined but never used. Open
node: function(value, id, selected, hovering) {},
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'edges' is not defined. Open
edges: new vis.DataSet(edges)
- Read upRead up
- Exclude checks
Disallow Undeclared Variables (no-undef)
This rule can help you locate potential ReferenceErrors resulting from misspellings of variable and parameter names, or accidental implicit globals (for example, from forgetting the var
keyword in a for
loop initializer).
Rule Details
Any reference to an undeclared variable causes a warning, unless the variable is explicitly mentioned in a /*global ...*/
comment.
Examples of incorrect code for this rule:
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
Examples of correct code for this rule with global
declaration:
/*global someFunction b:true*/
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
The b:true
syntax in /*global */
indicates that assignment to b
is correct.
Examples of incorrect code for this rule with global
declaration:
/*global b*/
/*eslint no-undef: "error"*/
b = 10;
By default, variables declared in /*global */
are read-only, therefore assignment is incorrect.
Options
-
typeof
set to true will warn for variables used inside typeof check (Default false).
typeof
Examples of correct code for the default { "typeof": false }
option:
/*eslint no-undef: "error"*/
if (typeof UndefinedIdentifier === "undefined") {
// do something ...
}
You can use this option if you want to prevent typeof
check on a variable which has not been declared.
Examples of incorrect code for the { "typeof": true }
option:
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Examples of correct code for the { "typeof": true }
option with global
declaration:
/*global a*/
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Environments
For convenience, ESLint provides shortcuts that pre-define global variables exposed by popular libraries and runtime environments. This rule supports these environments, as listed in Specifying Environments. A few examples are given below.
browser
Examples of correct code for this rule with browser
environment:
/*eslint no-undef: "error"*/
/*eslint-env browser*/
setTimeout(function() {
alert("Hello");
});
node
Examples of correct code for this rule with node
environment:
/*eslint no-undef: "error"*/
/*eslint-env node*/
var fs = require("fs");
module.exports = function() {
console.log(fs);
};
When Not To Use It
If explicit declaration of global variables is not to your taste.
Compatibility
This rule provides compatibility with treatment of global variables in JSHint and JSLint. Source: http://eslint.org/docs/rules/
'numEdges' is assigned a value but never used. Open
var [network, data, numNodes, numEdges] = createSampleNetwork({});
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'network' is already defined. Open
var [network, data, numNodes, numEdges] = createSampleNetwork();
- Read upRead up
- Exclude checks
disallow variable redeclaration (no-redeclare)
In JavaScript, it's possible to redeclare the same variable name using var
. This can lead to confusion as to where the variable is actually declared and initialized.
Rule Details
This rule is aimed at eliminating variables that have multiple declarations in the same scope.
Examples of incorrect code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
var a = 10;
Examples of correct code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
// ...
a = 10;
Options
This rule takes one optional argument, an object with a boolean property "builtinGlobals"
. It defaults to false
.
If set to true
, this rule also checks redeclaration of built-in globals, such as Object
, Array
, Number
...
builtinGlobals
Examples of incorrect code for the { "builtinGlobals": true }
option:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
var Object = 0;
Examples of incorrect code for the { "builtinGlobals": true }
option and the browser
environment:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
/*eslint-env browser*/
var top = 0;
The browser
environment has many built-in global variables (for example, top
). Some of built-in global variables cannot be redeclared.
Source: http://eslint.org/docs/rules/
'numNodes' is assigned a value but never used. Open
var [network, data, numNodes, numEdges] = createSampleNetwork(options);
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for (var id in network.body.nodes) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
'hovering' is defined but never used. Open
label: function(value, id, selected, hovering) {}
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'options' is not defined. Open
options.physics = false;
- Read upRead up
- Exclude checks
Disallow Undeclared Variables (no-undef)
This rule can help you locate potential ReferenceErrors resulting from misspellings of variable and parameter names, or accidental implicit globals (for example, from forgetting the var
keyword in a for
loop initializer).
Rule Details
Any reference to an undeclared variable causes a warning, unless the variable is explicitly mentioned in a /*global ...*/
comment.
Examples of incorrect code for this rule:
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
Examples of correct code for this rule with global
declaration:
/*global someFunction b:true*/
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
The b:true
syntax in /*global */
indicates that assignment to b
is correct.
Examples of incorrect code for this rule with global
declaration:
/*global b*/
/*eslint no-undef: "error"*/
b = 10;
By default, variables declared in /*global */
are read-only, therefore assignment is incorrect.
Options
-
typeof
set to true will warn for variables used inside typeof check (Default false).
typeof
Examples of correct code for the default { "typeof": false }
option:
/*eslint no-undef: "error"*/
if (typeof UndefinedIdentifier === "undefined") {
// do something ...
}
You can use this option if you want to prevent typeof
check on a variable which has not been declared.
Examples of incorrect code for the { "typeof": true }
option:
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Examples of correct code for the { "typeof": true }
option with global
declaration:
/*global a*/
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Environments
For convenience, ESLint provides shortcuts that pre-define global variables exposed by popular libraries and runtime environments. This rule supports these environments, as listed in Specifying Environments. A few examples are given below.
browser
Examples of correct code for this rule with browser
environment:
/*eslint no-undef: "error"*/
/*eslint-env browser*/
setTimeout(function() {
alert("Hello");
});
node
Examples of correct code for this rule with node
environment:
/*eslint no-undef: "error"*/
/*eslint-env node*/
var fs = require("fs");
module.exports = function() {
console.log(fs);
};
When Not To Use It
If explicit declaration of global variables is not to your taste.
Compatibility
This rule provides compatibility with treatment of global variables in JSHint and JSLint. Source: http://eslint.org/docs/rules/
'log' is defined but never used. Open
function log(network) {
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for (var id in network.body.edges) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
'data' is already defined. Open
var [network, data, numNodes, numEdges] = createSampleNetwork();
- Read upRead up
- Exclude checks
disallow variable redeclaration (no-redeclare)
In JavaScript, it's possible to redeclare the same variable name using var
. This can lead to confusion as to where the variable is actually declared and initialized.
Rule Details
This rule is aimed at eliminating variables that have multiple declarations in the same scope.
Examples of incorrect code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
var a = 10;
Examples of correct code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
// ...
a = 10;
Options
This rule takes one optional argument, an object with a boolean property "builtinGlobals"
. It defaults to false
.
If set to true
, this rule also checks redeclaration of built-in globals, such as Object
, Array
, Number
...
builtinGlobals
Examples of incorrect code for the { "builtinGlobals": true }
option:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
var Object = 0;
Examples of incorrect code for the { "builtinGlobals": true }
option and the browser
environment:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
/*eslint-env browser*/
var top = 0;
The browser
environment has many built-in global variables (for example, top
). Some of built-in global variables cannot be redeclared.
Source: http://eslint.org/docs/rules/
The body of a for-in should be wrapped in an if statement to filter unwanted properties from the prototype. Open
for(var m in node.containedNodes) {
- Read upRead up
- Exclude checks
Require Guarding for-in (guard-for-in)
Looping over objects with a for in
loop will include properties that are inherited through the prototype chain. This behavior can lead to unexpected items in your for loop.
for (key in foo) {
doSomething(key);
}
Note that simply checking foo.hasOwnProperty(key)
is likely to cause an error in some cases; see [no-prototype-builtins](no-prototype-builtins.md).
Rule Details
This rule is aimed at preventing unexpected behavior that could arise from using a for in
loop without filtering the results in the loop. As such, it will warn when for in
loops do not filter their results with an if
statement.
Examples of incorrect code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
doSomething(key);
}
Examples of correct code for this rule:
/*eslint guard-for-in: "error"*/
for (key in foo) {
if (Object.prototype.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
if ({}.hasOwnProperty.call(foo, key)) {
doSomething(key);
}
}
Related Rules
- [no-prototype-builtins](no-prototype-builtins.md)
Further Reading
'n' is defined but never used. Open
var joinAll_ = function(n) { return true ; }
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'options' is not defined. Open
var network = new vis.Network(container, data, options);
- Read upRead up
- Exclude checks
Disallow Undeclared Variables (no-undef)
This rule can help you locate potential ReferenceErrors resulting from misspellings of variable and parameter names, or accidental implicit globals (for example, from forgetting the var
keyword in a for
loop initializer).
Rule Details
Any reference to an undeclared variable causes a warning, unless the variable is explicitly mentioned in a /*global ...*/
comment.
Examples of incorrect code for this rule:
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
Examples of correct code for this rule with global
declaration:
/*global someFunction b:true*/
/*eslint no-undef: "error"*/
var a = someFunction();
b = 10;
The b:true
syntax in /*global */
indicates that assignment to b
is correct.
Examples of incorrect code for this rule with global
declaration:
/*global b*/
/*eslint no-undef: "error"*/
b = 10;
By default, variables declared in /*global */
are read-only, therefore assignment is incorrect.
Options
-
typeof
set to true will warn for variables used inside typeof check (Default false).
typeof
Examples of correct code for the default { "typeof": false }
option:
/*eslint no-undef: "error"*/
if (typeof UndefinedIdentifier === "undefined") {
// do something ...
}
You can use this option if you want to prevent typeof
check on a variable which has not been declared.
Examples of incorrect code for the { "typeof": true }
option:
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Examples of correct code for the { "typeof": true }
option with global
declaration:
/*global a*/
/*eslint no-undef: ["error", { "typeof": true }] */
if(typeof a === "string"){}
Environments
For convenience, ESLint provides shortcuts that pre-define global variables exposed by popular libraries and runtime environments. This rule supports these environments, as listed in Specifying Environments. A few examples are given below.
browser
Examples of correct code for this rule with browser
environment:
/*eslint no-undef: "error"*/
/*eslint-env browser*/
setTimeout(function() {
alert("Hello");
});
node
Examples of correct code for this rule with node
environment:
/*eslint no-undef: "error"*/
/*eslint-env node*/
var fs = require("fs");
module.exports = function() {
console.log(fs);
};
When Not To Use It
If explicit declaration of global variables is not to your taste.
Compatibility
This rule provides compatibility with treatment of global variables in JSHint and JSLint. Source: http://eslint.org/docs/rules/
'stdout' is assigned a value but never used. Open
var stdout = require('test-console').stdout;
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'data' is assigned a value but never used. Open
var [network, data, numNodes, numEdges] = createSampleNetwork(options);
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'hovering' is defined but never used. Open
label: function(value, id, selected, hovering) {}
- Read upRead up
- Exclude checks
Disallow Unused Variables (no-unused-vars)
Variables that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such variables take up space in the code and can lead to confusion by readers.
Rule Details
This rule is aimed at eliminating unused variables, functions, and parameters of functions.
A variable is considered to be used if any of the following are true:
- It represents a function that is called (
doSomething()
) - It is read (
var y = x
) - It is passed into a function as an argument (
doSomething(x)
) - It is read inside of a function that is passed to another function (
doSomething(function() { foo(); })
)
A variable is not considered to be used if it is only ever assigned to (var x = 5
) or declared.
Examples of incorrect code for this rule:
/*eslint no-unused-vars: "error"*/
/*global some_unused_var*/
// It checks variables you have defined as global
some_unused_var = 42;
var x;
// Write-only variables are not considered as used.
var y = 10;
y = 5;
// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;
// By default, unused arguments cause warnings.
(function(foo) {
return 5;
})();
// Unused recursive functions also cause warnings.
function fact(n) {
if (n < 2) return 1;
return n * fact(n - 1);
}
// When a function definition destructures an array, unused entries from the array also cause warnings.
function getY([x, y]) {
return y;
}
Examples of correct code for this rule:
/*eslint no-unused-vars: "error"*/
var x = 10;
alert(x);
// foo is considered used here
myFunc(function foo() {
// ...
}.bind(this));
(function(foo) {
return foo;
})();
var myFunc;
myFunc = setTimeout(function() {
// myFunc is considered used
myFunc();
}, 50);
// Only the second argument from the descructured array is used.
function getY([, y]) {
return y;
}
exported
In environments outside of CommonJS or ECMAScript modules, you may use var
to create a global variable that may be used by other scripts. You can use the /* exported variableName */
comment block to indicate that this variable is being exported and therefore should not be considered unused.
Note that /* exported */
has no effect for any of the following:
- when the environment is
node
orcommonjs
- when
parserOptions.sourceType
ismodule
- when
ecmaFeatures.globalReturn
istrue
The line comment // exported variableName
will not work as exported
is not line-specific.
Examples of correct code for /* exported variableName */
operation:
/* exported global_var */
var global_var = 42;
Options
This rule takes one argument which can be a string or an object. The string settings are the same as those of the vars
property (explained below).
By default this rule is enabled with all
option for variables and after-used
for arguments.
{
"rules": {
"no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": false }]
}
}
vars
The vars
option has two settings:
-
all
checks all variables for usage, including those in the global scope. This is the default setting. -
local
checks only that locally-declared variables are used but will allow global variables to be unused.
vars: local
Examples of correct code for the { "vars": "local" }
option:
/*eslint no-unused-vars: ["error", { "vars": "local" }]*/
/*global some_unused_var */
some_unused_var = 42;
varsIgnorePattern
The varsIgnorePattern
option specifies exceptions not to check for usage: variables whose names match a regexp pattern. For example, variables whose names contain ignored
or Ignored
.
Examples of correct code for the { "varsIgnorePattern": "[iI]gnored" }
option:
/*eslint no-unused-vars: ["error", { "varsIgnorePattern": "[iI]gnored" }]*/
var firstVarIgnored = 1;
var secondVar = 2;
console.log(secondVar);
args
The args
option has three settings:
-
after-used
- only the last argument must be used. This allows you, for instance, to have two named parameters to a function and as long as you use the second argument, ESLint will not warn you about the first. This is the default setting. -
all
- all named arguments must be used. -
none
- do not check arguments.
args: after-used
Examples of incorrect code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", { "args": "after-used" }]*/
// 1 error
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
Examples of correct code for the default { "args": "after-used" }
option:
/*eslint no-unused-vars: ["error", {"args": "after-used"}]*/
(function(foo, bar, baz) {
return baz;
})();
args: all
Examples of incorrect code for the { "args": "all" }
option:
/*eslint no-unused-vars: ["error", { "args": "all" }]*/
// 2 errors
// "foo" is defined but never used
// "baz" is defined but never used
(function(foo, bar, baz) {
return bar;
})();
args: none
Examples of correct code for the { "args": "none" }
option:
/*eslint no-unused-vars: ["error", { "args": "none" }]*/
(function(foo, bar, baz) {
return bar;
})();
ignoreRestSiblings
The ignoreRestSiblings
option is a boolean (default: false
). Using a Rest Property it is possible to "omit" properties from an object, but by default the sibling properties are marked as "unused". With this option enabled the rest property's siblings are ignored.
Examples of correct code for the { "ignoreRestSiblings": true }
option:
/*eslint no-unused-vars: ["error", { "ignoreRestSiblings": true }]*/
// 'type' is ignored because it has a rest property sibling.
var { type, ...coords } = data;
argsIgnorePattern
The argsIgnorePattern
option specifies exceptions not to check for usage: arguments whose names match a regexp pattern. For example, variables whose names begin with an underscore.
Examples of correct code for the { "argsIgnorePattern": "^_" }
option:
/*eslint no-unused-vars: ["error", { "argsIgnorePattern": "^_" }]*/
function foo(x, _y) {
return x + 1;
}
foo();
caughtErrors
The caughtErrors
option is used for catch
block arguments validation.
It has two settings:
-
none
- do not check error objects. This is the default setting. -
all
- all named arguments must be used.
caughtErrors: none
Not specifying this rule is equivalent of assigning it to none
.
Examples of correct code for the { "caughtErrors": "none" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrors: all
Examples of incorrect code for the { "caughtErrors": "all" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
// 1 error
// "err" is defined but never used
try {
//...
} catch (err) {
console.error("errors");
}
caughtErrorsIgnorePattern
The caughtErrorsIgnorePattern
option specifies exceptions not to check for usage: catch arguments whose names match a regexp pattern. For example, variables whose names begin with a string 'ignore'.
Examples of correct code for the { "caughtErrorsIgnorePattern": "^ignore" }
option:
/*eslint no-unused-vars: ["error", { "caughtErrorsIgnorePattern": "^ignore" }]*/
try {
//...
} catch (ignoreErr) {
console.error("errors");
}
When Not To Use It
If you don't want to be notified about unused variables or function arguments, you can safely turn this rule off. Source: http://eslint.org/docs/rules/
'numEdges' is already defined. Open
var [network, data, numNodes, numEdges] = createSampleNetwork();
- Read upRead up
- Exclude checks
disallow variable redeclaration (no-redeclare)
In JavaScript, it's possible to redeclare the same variable name using var
. This can lead to confusion as to where the variable is actually declared and initialized.
Rule Details
This rule is aimed at eliminating variables that have multiple declarations in the same scope.
Examples of incorrect code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
var a = 10;
Examples of correct code for this rule:
/*eslint no-redeclare: "error"*/
var a = 3;
// ...
a = 10;
Options
This rule takes one optional argument, an object with a boolean property "builtinGlobals"
. It defaults to false
.
If set to true
, this rule also checks redeclaration of built-in globals, such as Object
, Array
, Number
...
builtinGlobals
Examples of incorrect code for the { "builtinGlobals": true }
option:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
var Object = 0;
Examples of incorrect code for the { "builtinGlobals": true }
option and the browser
environment:
/*eslint no-redeclare: ["error", { "builtinGlobals": true }]*/
/*eslint-env browser*/
var top = 0;
The browser
environment has many built-in global variables (for example, top
). Some of built-in global variables cannot be redeclared.
Source: http://eslint.org/docs/rules/
TODO found Open
* Perhaps TODO: add unit test for passing string value for color option
- Exclude checks
TODO found Open
* TODO: consolidate this is necessary
- Exclude checks
TODO found Open
* TODO: consolidate this is necessary
- Exclude checks
Mixed spaces and tabs. Open
clusterTo(network, 'c1', [4], true);
- Read upRead up
- Exclude checks
disallow mixed spaces and tabs for indentation (no-mixed-spaces-and-tabs)
Most code conventions require either tabs or spaces be used for indentation. As such, it's usually an error if a single line of code is indented with both tabs and spaces.
Rule Details
This rule disallows mixed spaces and tabs for indentation.
Examples of incorrect code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->..return x + y;
return x + y;
}
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Examples of correct code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->return x + y;
return x + y;
}
Options
This rule has a string option.
-
"smart-tabs"
allows mixed spaces and tabs when the latter are used for alignment.
smart-tabs
Examples of correct code for this rule with the "smart-tabs"
option:
/*eslint no-mixed-spaces-and-tabs: ["error", "smart-tabs"]*/
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Further Reading
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc comment. Open
function checkChooserValues(item, chooser, labelChooser) {
- Read upRead up
- Exclude checks
require JSDoc comments (require-jsdoc)
JSDoc is a JavaScript API documentation generator. It uses specially-formatted comments inside of code to generate API documentation automatically. For example, this is what a JSDoc comment looks like for a function:
/**
* Adds two numbers together.
* @param {int} num1 The first number.
* @param {int} num2 The second number.
* @returns {int} The sum of the two numbers.
*/
function sum(num1, num2) {
return num1 + num2;
}
Some style guides require JSDoc comments for all functions as a way of explaining function behavior.
Rule Details
This rule requires JSDoc comments for specified nodes. Supported nodes:
"FunctionDeclaration"
"ClassDeclaration"
"MethodDefinition"
"ArrowFunctionExpression"
Options
This rule has a single object option:
-
"require"
requires JSDoc comments for the specified nodes
Default option settings are:
{
"require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": false,
"ClassDeclaration": false,
"ArrowFunctionExpression": false
}
}]
}
require
Examples of incorrect code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
function foo() {
return 10;
}
var foo = () => {
return 10;
}
class Test{
getDate(){}
}
Examples of correct code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
/**
* It returns 10
*/
function foo() {
return 10;
}
/**
* It returns test + 10
* @params {int} test - some number
* @returns {int} sum of test and 10
*/
var foo = (test) => {
return test + 10;
}
/**
* It returns 10
*/
var foo = () => {
return 10;
}
/**
* It returns 10
*/
var foo = function() {
return 10;
}
var array = [1,2,3];
array.filter(function(item) {
return item > 2;
});
/**
* It returns 10
*/
class Test{
/**
* returns the date
*/
getDate(){}
}
setTimeout(() => {}, 10); // since it's an anonymous arrow function
When Not To Use It
If you do not require JSDoc for your functions, then you can leave this rule off.
Related Rules
- [valid-jsdoc](valid-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'expected'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'expectedPresent'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'fontItem'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc comment. Open
function loadExample(path, noPhysics) {
- Read upRead up
- Exclude checks
require JSDoc comments (require-jsdoc)
JSDoc is a JavaScript API documentation generator. It uses specially-formatted comments inside of code to generate API documentation automatically. For example, this is what a JSDoc comment looks like for a function:
/**
* Adds two numbers together.
* @param {int} num1 The first number.
* @param {int} num2 The second number.
* @returns {int} The sum of the two numbers.
*/
function sum(num1, num2) {
return num1 + num2;
}
Some style guides require JSDoc comments for all functions as a way of explaining function behavior.
Rule Details
This rule requires JSDoc comments for specified nodes. Supported nodes:
"FunctionDeclaration"
"ClassDeclaration"
"MethodDefinition"
"ArrowFunctionExpression"
Options
This rule has a single object option:
-
"require"
requires JSDoc comments for the specified nodes
Default option settings are:
{
"require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": false,
"ClassDeclaration": false,
"ArrowFunctionExpression": false
}
}]
}
require
Examples of incorrect code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
function foo() {
return 10;
}
var foo = () => {
return 10;
}
class Test{
getDate(){}
}
Examples of correct code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
/**
* It returns 10
*/
function foo() {
return 10;
}
/**
* It returns test + 10
* @params {int} test - some number
* @returns {int} sum of test and 10
*/
var foo = (test) => {
return test + 10;
}
/**
* It returns 10
*/
var foo = () => {
return 10;
}
/**
* It returns 10
*/
var foo = function() {
return 10;
}
var array = [1,2,3];
array.filter(function(item) {
return item > 2;
});
/**
* It returns 10
*/
class Test{
/**
* returns the date
*/
getDate(){}
}
setTimeout(() => {}, 10); // since it's an anonymous arrow function
When Not To Use It
If you do not require JSDoc for your functions, then you can leave this rule off.
Related Rules
- [valid-jsdoc](valid-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'options'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc comment. Open
function firstEdge(network) {
- Read upRead up
- Exclude checks
require JSDoc comments (require-jsdoc)
JSDoc is a JavaScript API documentation generator. It uses specially-formatted comments inside of code to generate API documentation automatically. For example, this is what a JSDoc comment looks like for a function:
/**
* Adds two numbers together.
* @param {int} num1 The first number.
* @param {int} num2 The second number.
* @returns {int} The sum of the two numbers.
*/
function sum(num1, num2) {
return num1 + num2;
}
Some style guides require JSDoc comments for all functions as a way of explaining function behavior.
Rule Details
This rule requires JSDoc comments for specified nodes. Supported nodes:
"FunctionDeclaration"
"ClassDeclaration"
"MethodDefinition"
"ArrowFunctionExpression"
Options
This rule has a single object option:
-
"require"
requires JSDoc comments for the specified nodes
Default option settings are:
{
"require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": false,
"ClassDeclaration": false,
"ArrowFunctionExpression": false
}
}]
}
require
Examples of incorrect code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
function foo() {
return 10;
}
var foo = () => {
return 10;
}
class Test{
getDate(){}
}
Examples of correct code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
/**
* It returns 10
*/
function foo() {
return 10;
}
/**
* It returns test + 10
* @params {int} test - some number
* @returns {int} sum of test and 10
*/
var foo = (test) => {
return test + 10;
}
/**
* It returns 10
*/
var foo = () => {
return 10;
}
/**
* It returns 10
*/
var foo = function() {
return 10;
}
var array = [1,2,3];
array.filter(function(item) {
return item > 2;
});
/**
* It returns 10
*/
class Test{
/**
* returns the date
*/
getDate(){}
}
setTimeout(() => {}, 10); // since it's an anonymous arrow function
When Not To Use It
If you do not require JSDoc for your functions, then you can leave this rule off.
Related Rules
- [valid-jsdoc](valid-jsdoc.md) Source: http://eslint.org/docs/rules/
Mixed spaces and tabs. Open
clusterTo(network, 'c2', ['c1'], true);
- Read upRead up
- Exclude checks
disallow mixed spaces and tabs for indentation (no-mixed-spaces-and-tabs)
Most code conventions require either tabs or spaces be used for indentation. As such, it's usually an error if a single line of code is indented with both tabs and spaces.
Rule Details
This rule disallows mixed spaces and tabs for indentation.
Examples of incorrect code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->..return x + y;
return x + y;
}
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Examples of correct code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->return x + y;
return x + y;
}
Options
This rule has a string option.
-
"smart-tabs"
allows mixed spaces and tabs when the latter are used for alignment.
smart-tabs
Examples of correct code for this rule with the "smart-tabs"
option:
/*eslint no-mixed-spaces-and-tabs: ["error", "smart-tabs"]*/
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Further Reading
Missing JSDoc for parameter 'context'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'expectedVisible'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'expectedVisible'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'clusterId'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'allowSingle'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc comment. Open
function firstNode(network) {
- Read upRead up
- Exclude checks
require JSDoc comments (require-jsdoc)
JSDoc is a JavaScript API documentation generator. It uses specially-formatted comments inside of code to generate API documentation automatically. For example, this is what a JSDoc comment looks like for a function:
/**
* Adds two numbers together.
* @param {int} num1 The first number.
* @param {int} num2 The second number.
* @returns {int} The sum of the two numbers.
*/
function sum(num1, num2) {
return num1 + num2;
}
Some style guides require JSDoc comments for all functions as a way of explaining function behavior.
Rule Details
This rule requires JSDoc comments for specified nodes. Supported nodes:
"FunctionDeclaration"
"ClassDeclaration"
"MethodDefinition"
"ArrowFunctionExpression"
Options
This rule has a single object option:
-
"require"
requires JSDoc comments for the specified nodes
Default option settings are:
{
"require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": false,
"ClassDeclaration": false,
"ArrowFunctionExpression": false
}
}]
}
require
Examples of incorrect code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
function foo() {
return 10;
}
var foo = () => {
return 10;
}
class Test{
getDate(){}
}
Examples of correct code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true } }
option:
/*eslint "require-jsdoc": ["error", {
"require": {
"FunctionDeclaration": true,
"MethodDefinition": true,
"ClassDeclaration": true
}
}]*/
/**
* It returns 10
*/
function foo() {
return 10;
}
/**
* It returns test + 10
* @params {int} test - some number
* @returns {int} sum of test and 10
*/
var foo = (test) => {
return test + 10;
}
/**
* It returns 10
*/
var foo = () => {
return 10;
}
/**
* It returns 10
*/
var foo = function() {
return 10;
}
var array = [1,2,3];
array.filter(function(item) {
return item > 2;
});
/**
* It returns 10
*/
class Test{
/**
* returns the date
*/
getDate(){}
}
setTimeout(() => {}, 10); // since it's an anonymous arrow function
When Not To Use It
If you do not require JSDoc for your functions, then you can leave this rule off.
Related Rules
- [valid-jsdoc](valid-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'list'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'checkStrict'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'options'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'network'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'expectedPresent'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'nodeList'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Mixed spaces and tabs. Open
clusterTo(network, 'c3', ['c2'], true);
- Read upRead up
- Exclude checks
disallow mixed spaces and tabs for indentation (no-mixed-spaces-and-tabs)
Most code conventions require either tabs or spaces be used for indentation. As such, it's usually an error if a single line of code is indented with both tabs and spaces.
Rule Details
This rule disallows mixed spaces and tabs for indentation.
Examples of incorrect code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->..return x + y;
return x + y;
}
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Examples of correct code for this rule:
/*eslint no-mixed-spaces-and-tabs: "error"*/
function add(x, y) {
// --->return x + y;
return x + y;
}
Options
This rule has a string option.
-
"smart-tabs"
allows mixed spaces and tabs when the latter are used for alignment.
smart-tabs
Examples of correct code for this rule with the "smart-tabs"
option:
/*eslint no-mixed-spaces-and-tabs: ["error", "smart-tabs"]*/
function main() {
// --->var x = 5,
// --->....y = 7;
var x = 5,
y = 7;
}
Further Reading
Missing JSDoc @returns for function. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/
Missing JSDoc for parameter 'recieved'. Open
/**
- Read upRead up
- Exclude checks
enforce valid JSDoc comments (valid-jsdoc)
JSDoc generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function:
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
If comments are invalid because of typing mistakes, then documentation will be incomplete.
If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused.
Rule Details
This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:
- missing parameter tag:
@arg
,@argument
, or@param
- inconsistent order of parameter names in a comment compared to the function or method
- missing return tag:
@return
or@returns
- missing parameter or return type
- missing parameter or return description
- syntax error
This rule does not report missing JSDoc comments for classes, functions, or methods.
Note: This rule does not support all of the Google Closure documentation tool's use cases. As such, some code such as (/**number*/ n => n * 2);
will be flagged as missing appropriate function JSDoc comments even though /**number*/
is intended to be a type hint and not a documentation block for the function. We don't recommend using this rule if you use type hints in this way.
Examples of incorrect code for this rule:
/*eslint valid-jsdoc: "error"*/
// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
* Add two numbers.
* @param {number} num The first number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// missing brace
// missing @returns tag
/**
* @param {string name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
// missing parameter type for num1
// missing parameter description for num2
/**
* Represents a sum.
* @constructor
* @param num1 The first number.
* @param {number} num2
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
Examples of correct code for this rule:
/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
// @constructor tag allows missing @returns tag
/**
* Represents a sum.
* @constructor
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
// class constructor allows missing @returns tag
/**
* Represents a sum.
*/
class Sum {
/**
* @param {number} num1 The first number.
* @param {number} num2 The second number.
*/
constructor(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
}
// @abstract tag allows @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
/**
* @override
*/
mustRender (state) {
return state !== this.state; // shallow comparison
}
}
Options
This rule has an object option:
-
"prefer"
enforces consistent documentation tags specified by an object whose properties mean instead of key use value (for example,"return": "returns"
means instead of@return
use@returns
) -
"preferType"
enforces consistent type strings specified by an object whose properties mean instead of key use value (for example,"object": "Object"
means instead ofobject
useObject
) -
"requireReturn"
requires a return tag:-
true
(default) even if the function or method does not have areturn
statement (this option value does not apply to constructors) -
false
if and only if the function or method has areturn
statement (this option value does apply to constructors)
-
-
"requireReturnType": false
allows missing type in return tags -
"matchDescription"
specifies (as a string) a regular expression to match the description in each JSDoc comment (for example,".+"
requires a description; this option does not apply to descriptions in parameter or return tags) -
"requireParamDescription": false
allows missing description in parameter tags -
"requireReturnDescription": false
allows missing description in return tags
prefer
Examples of additional incorrect code for this rule with sample "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }
options:
/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @arg {int} num1 The first number.
* @arg {int} num2 The second number.
* @return {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Represents a sum.
* @class
* @argument {number} num1 The first number.
* @argument {number} num2 The second number.
*/
function sum(num1, num2) {
this.num1 = num1;
this.num2 = num2;
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @virtual
* @argument {Object} state The new state of the widget.
* @return {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
preferType
Examples of additional incorrect code for this rule with sample "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }
options:
/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/
/**
* Add two numbers.
* @param {Number} num1 The first number.
* @param {Number} num2 The second number.
* @returns {Number} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
/**
* Output a greeting as a side effect.
* @param {String} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @abstract
* @param {object} state The new state of the widget.
* @returns {Boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
requireReturn
Examples of additional incorrect code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
// unexpected @returns tag because function has no `return` statement
/**
* @param {string} name Whom to greet.
* @returns {string} The greeting.
*/
function greet(name) {
console.log("Hello " + name);
}
// add @abstract tag to allow @returns tag without `return` statement
class Widget {
/**
* When the state changes, does it affect the rendered appearance?
* @param {Object} state The new state of the widget.
* @returns {boolean} Is current appearance inconsistent with new state?
*/
mustRender (state) {
throw new Error("Widget subclass did not implement mustRender");
}
}
Example of additional correct code for this rule with the "requireReturn": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/
/**
* @param {string} name Whom to greet.
*/
function greet(name) {
console.log("Hello " + name);
}
requireReturnType
Example of additional correct code for this rule with the "requireReturnType": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
matchDescription
Example of additional incorrect code for this rule with a sample "matchDescription": ".+"
option:
/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/
// missing function description
/**
* @param {string} name Whom to greet.
* @returns {void}
*/
function greet(name) {
console.log("Hello " + name);
}
requireParamDescription
Example of additional correct code for this rule with the "requireParamDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/
/**
* Add two numbers.
* @param {int} num1
* @param {int} num2
* @returns {int} The sum of the two numbers.
*/
function add(num1, num2) {
return num1 + num2;
}
requireReturnDescription
Example of additional correct code for this rule with the "requireReturnDescription": false
option:
/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/
/**
* Add two numbers.
* @param {number} num1 The first number.
* @param {number} num2 The second number.
* @returns {number}
*/
function add(num1, num2) {
return num1 + num2;
}
When Not To Use It
If you aren't using JSDoc, then you can safely turn this rule off.
Further Reading
Related Rules
- [require-jsdoc](require-jsdoc.md) Source: http://eslint.org/docs/rules/