Expected to return a value at the end of function 'getDoc'. Open
function getDoc(options) {
- Read upRead up
- Exclude checks
require return
statements to either always or never specify values (consistent-return)
Unlike statically-typed languages which enforce that a function returns a specified type of value, JavaScript allows different code paths in a function to return different types of values.
A confusing aspect of JavaScript is that a function returns undefined
if any of the following are true:
- it does not execute a
return
statement before it exits - it executes
return
which does not specify a value explicitly - it executes
return undefined
- it executes
return void
followed by an expression (for example, a function call) - it executes
return
followed by any other expression which evaluates toundefined
If any code paths in a function return a value explicitly but some code path do not return a value explicitly, it might be a typing mistake, especially in a large function. In the following example:
- a code path through the function returns a Boolean value
true
- another code path does not return a value explicitly, therefore returns
undefined
implicitly
function doSomething(condition) {
if (condition) {
return true;
} else {
return;
}
}
Rule Details
This rule requires return
statements to either always or never specify values. This rule ignores function definitions where the name begins with an uppercase letter, because constructors (when invoked with the new
operator) return the instantiated object implicitly if they do not return another object explicitly.
Examples of incorrect code for this rule:
/*eslint consistent-return: "error"*/
function doSomething(condition) {
if (condition) {
return true;
} else {
return;
}
}
function doSomething(condition) {
if (condition) {
return true;
}
}
Examples of correct code for this rule:
/*eslint consistent-return: "error"*/
function doSomething(condition) {
if (condition) {
return true;
} else {
return false;
}
}
function Foo() {
if (!(this instanceof Foo)) {
return new Foo();
}
this.a = 0;
}
Options
This rule has an object option:
-
"treatUndefinedAsUnspecified": false
(default) always either specify values or returnundefined
implicitly only. -
"treatUndefinedAsUnspecified": true
always either specify values or returnundefined
explicitly or implicitly.
treatUndefinedAsUnspecified
Examples of incorrect code for this rule with the default { "treatUndefinedAsUnspecified": false }
option:
/*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": false }]*/
function foo(callback) {
if (callback) {
return void callback();
}
// no return statement
}
function bar(condition) {
if (condition) {
return undefined;
}
// no return statement
}
Examples of incorrect code for this rule with the { "treatUndefinedAsUnspecified": true }
option:
/*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
function foo(callback) {
if (callback) {
return void callback();
}
return true;
}
function bar(condition) {
if (condition) {
return undefined;
}
return true;
}
Examples of correct code for this rule with the { "treatUndefinedAsUnspecified": true }
option:
/*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
function foo(callback) {
if (callback) {
return void callback();
}
// no return statement
}
function bar(condition) {
if (condition) {
return undefined;
}
// no return statement
}
When Not To Use It
If you want to allow functions to have different return
behavior depending on code branching, then it is safe to disable this rule.
Source: http://eslint.org/docs/rules/
Unexpected console statement. Open
console.log(`redoc/getDocSet: Failed to load repo data for ${options.repo}`);
- Read upRead up
- Exclude checks
disallow the use of console
(no-console)
In JavaScript that is designed to be executed in the browser, it's considered a best practice to avoid using methods on console
. Such messages are considered to be for debugging purposes and therefore not suitable to ship to the client. In general, calls using console
should be stripped before being pushed to production.
console.log("Made it here.");
console.error("That shouldn't have happened.");
Rule Details
This rule disallows calls to methods of the console
object.
Examples of incorrect code for this rule:
/*eslint no-console: "error"*/
console.log("Log a debug level message.");
console.warn("Log a warn level message.");
console.error("Log an error level message.");
Examples of correct code for this rule:
/*eslint no-console: "error"*/
// custom console
Console.log("Hello world!");
Options
This rule has an object option for exceptions:
-
"allow"
has an array of strings which are allowed methods of theconsole
object
Examples of additional correct code for this rule with a sample { "allow": ["warn", "error"] }
option:
/*eslint no-console: ["error", { allow: ["warn", "error"] }] */
console.warn("Log a warn level message.");
console.error("Log an error level message.");
When Not To Use It
If you're using Node.js, however, console
is used to output information to the user and so is not strictly used for debugging purposes. If you are developing for Node.js then you most likely do not want this rule enabled.
Related Rules
- [no-alert](no-alert.md)
- [no-debugger](no-debugger.md) Source: http://eslint.org/docs/rules/
Expected JSDoc for 'options' but found 'doc'. 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/