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

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"
"FunctionExpression"

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,
            "FunctionExpression": false
        }
    }]
}
1
2
3
4
5
6
7
8
9
10
11

require

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 {int} test - some number
 * @returns {int} 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

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

Version

This rule was introduced in ESLint v1.4.0 and removed in v9.0.0-alpha.0.

Edit this page