]>
Commit | Line | Data |
---|---|---|
eb39fafa DC |
1 | # require JSDoc comments (require-jsdoc) |
2 | ||
3 | This rule was [**deprecated**](https://eslint.org/blog/2018/11/jsdoc-end-of-life) in ESLint v5.10.0. | |
4 | ||
5 | [JSDoc](http://usejsdoc.org) 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: | |
6 | ||
7 | ```js | |
8 | /** | |
9 | * Adds two numbers together. | |
10 | * @param {int} num1 The first number. | |
11 | * @param {int} num2 The second number. | |
12 | * @returns {int} The sum of the two numbers. | |
13 | */ | |
14 | function sum(num1, num2) { | |
15 | return num1 + num2; | |
16 | } | |
17 | ``` | |
18 | ||
19 | Some style guides require JSDoc comments for all functions as a way of explaining function behavior. | |
20 | ||
21 | ## Rule Details | |
22 | ||
23 | This rule requires JSDoc comments for specified nodes. Supported nodes: | |
24 | ||
25 | * `"FunctionDeclaration"` | |
26 | * `"ClassDeclaration"` | |
27 | * `"MethodDefinition"` | |
28 | * `"ArrowFunctionExpression"` | |
29 | * `"FunctionExpression"` | |
30 | ||
31 | ## Options | |
32 | ||
33 | This rule has a single object option: | |
34 | ||
35 | * `"require"` requires JSDoc comments for the specified nodes | |
36 | ||
37 | Default option settings are: | |
38 | ||
39 | ```json | |
40 | { | |
41 | "require-jsdoc": ["error", { | |
42 | "require": { | |
43 | "FunctionDeclaration": true, | |
44 | "MethodDefinition": false, | |
45 | "ClassDeclaration": false, | |
46 | "ArrowFunctionExpression": false, | |
47 | "FunctionExpression": false | |
48 | } | |
49 | }] | |
50 | } | |
51 | ``` | |
52 | ||
53 | ### require | |
54 | ||
55 | Examples of **incorrect** code for this rule with the `{ "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true, "FunctionExpression": true } }` option: | |
56 | ||
57 | ```js | |
58 | /*eslint "require-jsdoc": ["error", { | |
59 | "require": { | |
60 | "FunctionDeclaration": true, | |
61 | "MethodDefinition": true, | |
62 | "ClassDeclaration": true, | |
63 | "ArrowFunctionExpression": true, | |
64 | "FunctionExpression": true | |
65 | } | |
66 | }]*/ | |
67 | ||
68 | function foo() { | |
69 | return 10; | |
70 | } | |
71 | ||
72 | var foo = () => { | |
73 | return 10; | |
74 | }; | |
75 | ||
76 | class Foo { | |
77 | bar() { | |
78 | return 10; | |
79 | } | |
80 | } | |
81 | ||
82 | var foo = function() { | |
83 | return 10; | |
84 | }; | |
85 | ||
86 | var foo = { | |
87 | bar: function() { | |
88 | return 10; | |
89 | }, | |
90 | ||
91 | baz() { | |
92 | return 10; | |
93 | } | |
94 | }; | |
95 | ``` | |
96 | ||
97 | Examples of **correct** code for this rule with the `{ "require": { "FunctionDeclaration": true, "MethodDefinition": true, "ClassDeclaration": true, "ArrowFunctionExpression": true, "FunctionExpression": true } }` option: | |
98 | ||
99 | ```js | |
100 | /*eslint "require-jsdoc": ["error", { | |
101 | "require": { | |
102 | "FunctionDeclaration": true, | |
103 | "MethodDefinition": true, | |
104 | "ClassDeclaration": true, | |
105 | "ArrowFunctionExpression": true, | |
106 | "FunctionExpression": true | |
107 | } | |
108 | }]*/ | |
109 | ||
110 | /** | |
111 | * It returns 10 | |
112 | */ | |
113 | function foo() { | |
114 | return 10; | |
115 | } | |
116 | ||
117 | /** | |
118 | * It returns test + 10 | |
119 | * @params {int} test - some number | |
120 | * @returns {int} sum of test and 10 | |
121 | */ | |
122 | var foo = (test) => { | |
123 | return test + 10; | |
124 | } | |
125 | ||
126 | /** | |
127 | * It returns 10 | |
128 | */ | |
129 | var foo = () => { | |
130 | return 10; | |
131 | } | |
132 | ||
133 | /** | |
134 | * It returns 10 | |
135 | */ | |
136 | var foo = function() { | |
137 | return 10; | |
138 | } | |
139 | ||
140 | var array = [1,2,3]; | |
141 | array.filter(function(item) { | |
142 | return item > 2; | |
143 | }); | |
144 | ||
145 | /** | |
146 | * A class that can return the number 10 | |
147 | */ | |
148 | class Foo { | |
149 | /** | |
150 | * It returns 10 | |
151 | */ | |
152 | bar() { | |
153 | return 10; | |
154 | } | |
155 | } | |
156 | ||
157 | /** | |
158 | * It returns 10 | |
159 | */ | |
160 | var foo = function() { | |
161 | return 10; | |
162 | }; | |
163 | ||
164 | var foo = { | |
165 | /** | |
166 | * It returns 10 | |
167 | */ | |
168 | bar: function() { | |
169 | return 10; | |
170 | }, | |
171 | ||
172 | /** | |
173 | * It returns 10 | |
174 | */ | |
175 | baz() { | |
176 | return 10; | |
177 | } | |
178 | }; | |
179 | ||
180 | setTimeout(() => {}, 10); // since it's an anonymous arrow function | |
181 | ``` | |
182 | ||
183 | ## When Not To Use It | |
184 | ||
185 | If you do not require JSDoc for your functions, then you can leave this rule off. | |
186 | ||
187 | ## Related Rules | |
188 | ||
189 | * [valid-jsdoc](valid-jsdoc.md) |