valid-jsdoc - ESLint - 插件化的 JavaScript 代码检查工具

相关文章推荐

活泼的围巾 · 交易费用 | Solana· 3 月前 ·

英勇无比的日记本 · 争夺“智驾芯片第一股”的地平线和黑芝麻，谁更 ...· 3 月前 ·

绅士的冰淇淋 · 没收任润厚非法所得案· 4 月前 ·

小猫猫 · LLM Visualization· 5 月前 ·

买醉的钥匙 · 试点职务科技成果“全部赋权”，上海推重磅改革 ...· 9 月前 ·

这个规则在 ESLint v5.10.0 中废弃。

JSDoc 从 JavaScript 代码中特殊格式的注释中生成应用程序编程接口（API）文档。例如，这是一个函数的 JSDoc 注释。

* 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 ;

如果注释因为错别字而失效，那么文档将是不完整的。

如果注释是不一致的，因为当函数定义被修改时，它们没有被更新，那么读者可能会感到困惑。

该规则执行有效和一致的 JSDoc 注释。它报告以下任何问题。

缺少参数标签：


    @arg

、


    @argument

或


    @param

。

与函数或方法相比，注释中的参数名称顺序不一致

缺少返回标签：


    @return

或


    @returns

。

缺少参数或返回类型

缺少参数或返回的描述

本规则不报告类、函数或方法的 JSDoc 注释缺失。

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

使用此规则的错误示例：

/*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

使用此规则的正确示例：

/*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
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

此规则选项为对象：


    "prefer"

执行一致的文档标签，由一个对象指定，其属性意味着用值代替键（如


    "return": "returns"

意味着用


    @return

代替


    @returns

)


    "preferType"

强制执行一致的类型字符串，该对象的属性意味着使用值而不是键（如


    "object": "Object"

意味着使用


    Object

代替


    object

）


    "requireReturn"

需要有返回标签：


    true

（默认值）即使函数或方法没有


    return

语句（该选项值不适用于构造函数）


    false

当且仅当 函数或方法使用


    return

语句或返回一个值，例如


    async

函数（此选项值适用于构造函数）


    "requireReturnType": false

允许在返回标签中缺少类型。


    "matchDescription"

指定（作为一个字符串）一个正则表达式来匹配每个 JSDoc 注释中的描述（如


    ".+"

需要一个描述；这个选项不适用于参数或返回标签中的描述）


    "requireParamDescription": false

允许参数标签中缺少描述


    "requireReturnDescription": false

允许在返回标签中缺少描述


    "requireParamType": false

允许在参数标签中缺失类型。

prefer

使用此规则与示例的 "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } 选项的额外错误示例：

/*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");
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

preferType

使用此规则与示例的 "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } 选项的额外错误示例：

/*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");
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

requireReturn

使用此规则与 "requireReturn": false 选项的的额外错误示例：

/*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

使用此规则与 "requireReturn": false 选项的的额外正确示例：

/*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

requireReturnType

使用此规则与 "requireReturnType": false 选项的的额外正确示例：

/*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

requireParamType

使用此规则与 "requireParamType": false 选项的额外正确示例：

/*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

matchDescription

使用此规则与示例的 "matchDescription": ".+" 选项的额外错误示例：

/*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

requireParamDescription

使用此规则与 "requireParamDescription": false 选项的额外正确示例：

/*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

requireReturnDescription

使用此规则与 "requireReturnDescription": false 选项的额外正确示例：

/*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

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