valid-jsdoc

JSDoc 从 JavaScript 代码中特殊格式的注释生成应用编程接口 (API) 文档。例如，这是一个函数的 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;
}
1
2
3
4
5
6
7
8
9
10
11
12
13

如果由于输入错误而导致注释无效，则文档将不完整。

¥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

此规则强制执行有效且一致的 JSDoc 注释。它报告以下任何问题：

¥This rule enforces valid and consistent JSDoc comments. It reports any of the following problems:

缺少参数标签：@arg、@argument 或 @param

¥missing parameter tag: @arg, @argument, or @param
与函数或方法相比，注释中参数名称的顺序不一致

¥inconsistent order of parameter names in a comment compared to the function or method
缺少返回标签：@return 或 @returns

¥missing return tag: @return or @returns
缺少参数或返回类型

¥missing parameter or return type
缺少参数或返回描述

¥missing parameter or return description
语法错误

¥syntax error

此规则不会报告缺少的类、函数或方法的 JSDoc 注释。

¥This rule does not report missing JSDoc comments for classes, functions, or methods.

注意：此规则不支持 Google Closure 文档工具的所有用例。因此，某些代码（例如 (/**number*/ n => n * 2);）将被标记为缺少适当的函数 JSDoc 注释，即使 /**number*/ 旨在作为函数的类型提示而不是文档块。如果你以这种方式使用类型提示，我们不建议使用此规则。

¥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;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

此规则的正确代码示例：

¥Examples of correct code for this rule:

/*eslint valid-jsdoc: "error"*/

/**

 * 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
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

选项

¥Options

此规则有一个对象选项：

¥This rule has an object option:

"prefer" 强制由对象指定一致的文档标签，该对象的属性意味着而不是关键使用值（例如，"return": "returns" 意味着使用 @returns 而不是 @return）

¥"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" 强制由其属性表示而不是键使用值的对象指定的一致类型字符串（例如，"object": "Object" 表示使用 Object 而不是 object）

¥"preferType" enforces consistent type strings specified by an object whose properties mean instead of key use value (for example, "object": "Object" means instead of object use Object)
"requireReturn" 需要返回标签：

¥"requireReturn" requires a return tag:
- true（默认），即使函数或方法没有 return 语句（此选项值不适用于构造函数）
  
  ¥true (default) even if the function or method does not have a return statement (this option value does not apply to constructors)
- false 当且仅当函数或方法有 return 语句或返回一个值，例如 async 函数（此选项值确实适用于构造函数）
  
  ¥false if and only if the function or method has a return statement or returns a value e.g. async function (this option value does apply to constructors)
"requireReturnType": false 允许返回标签中缺少类型

¥"requireReturnType": false allows missing type in return tags
"matchDescription" 指定（作为字符串）一个正则表达式来匹配每个 JSDoc 注释中的描述（例如，".+" 需要一个描述；此选项不适用于参数或返回标记中的描述）

¥"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 允许参数标签中缺少描述

¥"requireParamDescription": false allows missing description in parameter tags
"requireReturnDescription": false 允许返回标签中缺少描述

¥"requireReturnDescription": false allows missing description in return tags
"requireParamType": false 允许参数标签中缺少类型

¥"requireParamType": false allows missing type in parameter tags

prefer

此规则的其他错误代码示例以及示例 "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } 选项：

¥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" } }]*/

/**

 * 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");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

preferType

此规则的其他错误代码示例以及示例 "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } 选项：

¥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" } }]*/

/**

 * 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");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

requireReturn

使用 "requireReturn": false 选项的此规则的其他错误代码示例：

¥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");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

使用 "requireReturn": false 选项的此规则的附加正确代码示例：

¥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);
}
1
2
3
4
5
6
7
8
9

requireReturnType

使用 "requireReturnType": false 选项的此规则的附加正确代码示例：

¥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;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

requireParamType

使用 "requireParamType": false 选项的此规则的附加正确代码示例：

¥Example of additional correct code for this rule with the "requireParamType": false option:

/*eslint valid-jsdoc: ["error", { "requireParamType": false }]*/

/**

 * Add two numbers.

 * @param num1 The first number.

 * @param num2 The second number.

 * @returns {number} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

matchDescription

此规则的其他错误代码示例以及示例 "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);
}
1
2
3
4
5
6
7
8
9
10
11
12

requireParamDescription

使用 "requireParamDescription": false 选项的此规则的附加正确代码示例：

¥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;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

requireReturnDescription

使用 "requireReturnDescription": false 选项的此规则的附加正确代码示例：

¥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;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

何时不使用

¥When Not To Use It

如果你不使用 JSDoc，那么你可以安全地关闭此规则。

¥If you aren’t using JSDoc, then you can safely turn this rule off.

版本

此规则是在 ESLint v0.4.0 中引入，并在 v9.0.0-alpha.0 中删除。

进阶读物

Use JSDoc: Index
jsdoc.nodejs.cn