require-jsdoc

JSDoc 是一个 JavaScript API 文档生成器。它使用代码内部的特殊格式注释来自动生成 API 文档。例如，这就是一个函数的 JSDoc 注释的样子：

/**
 * Adds two numbers together.
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 * @returns {number} The sum of the two numbers.
 */
function sum(num1, num2) {
    return num1 + num2;
}
1
2
3
4
5
6
7
8
9

一些风格指南要求所有函数的 JSDoc 注释作为解释函数行为的一种方式。

🌐 Some style guides require JSDoc comments for all functions as a way of explaining function behavior.

规则详情

🌐 Rule Details

此规则要求对指定节点使用 JSDoc 注释。支持的节点：

🌐 This rule requires JSDoc comments for specified nodes. Supported nodes:

"FunctionDeclaration"
"ClassDeclaration"
"MethodDefinition"
"ArrowFunctionExpression"
"FunctionExpression"

选项

🌐 Options

此规则有一个对象选项：

🌐 This rule has a single object option:

"require" 要求对指定的节点使用 JSDoc 注释

默认选项设置为：

🌐 Default option settings are:

{
    "require-jsdoc": ["error", {
        "require": {
            "FunctionDeclaration": true,
            "MethodDefinition": false,
            "ClassDeclaration": false,
            "ArrowFunctionExpression": false,
            "FunctionExpression": false
        }
    }]
}
1
2
3
4
5
6
7
8
9
10
11

require

使用 { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true, "FunctionExpression": true } } 选项时违反此规则的错误代码示例：

🌐 Examples of incorrect code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true, "FunctionExpression": true } } option:

/*eslint "require-jsdoc": ["error", {
    "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true,
        "ArrowFunctionExpression": true,
        "FunctionExpression": true
    }
}]*/

function foo() {
    return 10;
}

var bar = () => {
    return 10;
};

class Foo {
    bar() {
        return 10;
    }
}

var bar = function() {
    return 10;
};

var bar = {
    bar: function() {
        return 10;
    },

    baz() {
        return 10;
    }
};
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

🌐 Examples of correct code for this rule with the { "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true, "FunctionExpression": true } } option:

/*eslint "require-jsdoc": ["error", {
    "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true,
        "ArrowFunctionExpression": true,
        "FunctionExpression": true
    }
}]*/

/**
 * It returns 10
 */
function foo() {
    return 10;
}

/**
 * It returns test + 10
 * @params {number} test - some number
 * @returns {number} sum of test and 10
 */
var bar = (test) => {
    return test + 10;
}

/**
 * It returns 10
 */
var bar = () => {
    return 10;
}

/**
 * It returns 10
 */
var bar = function() {
    return 10;
}

var array = [1,2,3];
array.filter(function(item) {
    return item > 2;
});

/**
 * A class that can return the number 10
 */
class Foo {
    /**
    * It returns 10
    */
    bar() {
        return 10;
    }
}

/**
 * It returns 10
 */
var bar = function() {
    return 10;
};

var bar = {
    /**
    * It returns 10
    */
    bar: function() {
        return 10;
    },

    /**
    * It returns 10
    */
    baz() {
        return 10;
    }
};

setTimeout(() => {}, 10); // since it's an anonymous arrow function
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

何时不使用

🌐 When Not To Use It

如果你的函数不需要 JSDoc，则可以关闭此规则。

🌐 If you do not require JSDoc for your functions, then you can leave this rule off.

版本

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

require-jsdoc

规则详情

选项

require

何时不使用

相关规则

版本