]>
Commit | Line | Data |
---|---|---|
eb39fafa DC |
1 | # enforce valid JSDoc comments (valid-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) generates application programming interface (API) documentation from specially-formatted comments in JavaScript code. For example, this is a JSDoc comment for a function: | |
6 | ||
7 | ```js | |
8 | /** | |
9 | * Add two numbers. | |
10 | * @param {number} num1 The first number. | |
11 | * @param {number} num2 The second number. | |
12 | * @returns {number} The sum of the two numbers. | |
13 | */ | |
14 | function add(num1, num2) { | |
15 | return num1 + num2; | |
16 | } | |
17 | ``` | |
18 | ||
19 | If comments are invalid because of typing mistakes, then documentation will be incomplete. | |
20 | ||
21 | If comments are inconsistent because they are not updated when function definitions are modified, then readers might become confused. | |
22 | ||
23 | ## Rule Details | |
24 | ||
25 | This rule enforces valid and consistent JSDoc comments. It reports any of the following problems: | |
26 | ||
27 | * missing parameter tag: `@arg`, `@argument`, or `@param` | |
28 | * inconsistent order of parameter names in a comment compared to the function or method | |
29 | * missing return tag: `@return` or `@returns` | |
30 | * missing parameter or return type | |
31 | * missing parameter or return description | |
32 | * syntax error | |
33 | ||
34 | This rule does not report missing JSDoc comments for classes, functions, or methods. | |
35 | ||
36 | **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. | |
37 | ||
38 | Examples of **incorrect** code for this rule: | |
39 | ||
40 | ```js | |
41 | /*eslint valid-jsdoc: "error"*/ | |
42 | ||
43 | // expected @param tag for parameter num1 but found num instead | |
44 | // missing @param tag for parameter num2 | |
45 | // missing return type | |
46 | /** | |
47 | * Add two numbers. | |
48 | * @param {number} num The first number. | |
49 | * @returns The sum of the two numbers. | |
50 | */ | |
51 | function add(num1, num2) { | |
52 | return num1 + num2; | |
53 | } | |
54 | ||
55 | // missing brace | |
56 | // missing @returns tag | |
57 | /** | |
58 | * @param {string name Whom to greet. | |
59 | */ | |
60 | function greet(name) { | |
61 | console.log("Hello " + name); | |
62 | } | |
63 | ||
64 | // missing parameter type for num1 | |
65 | // missing parameter description for num2 | |
66 | /** | |
67 | * Represents a sum. | |
68 | * @constructor | |
69 | * @param num1 The first number. | |
70 | * @param {number} num2 | |
71 | */ | |
72 | function sum(num1, num2) { | |
73 | this.num1 = num1; | |
74 | this.num2 = num2; | |
75 | } | |
76 | ``` | |
77 | ||
78 | Examples of **correct** code for this rule: | |
79 | ||
80 | ```js | |
81 | /*eslint valid-jsdoc: "error"*/ | |
82 | /*eslint-env es6*/ | |
83 | ||
84 | /** | |
85 | * Add two numbers. | |
86 | * @param {number} num1 The first number. | |
87 | * @param {number} num2 The second number. | |
88 | * @returns {number} The sum of the two numbers. | |
89 | */ | |
90 | function add(num1, num2) { | |
91 | return num1 + num2; | |
92 | } | |
93 | ||
94 | // default options allow missing function description | |
95 | // return type `void` means the function has no `return` statement | |
96 | /** | |
97 | * @param {string} name Whom to greet. | |
98 | * @returns {void} | |
99 | */ | |
100 | function greet(name) { | |
101 | console.log("Hello " + name); | |
102 | } | |
103 | ||
104 | // @constructor tag allows missing @returns tag | |
105 | /** | |
106 | * Represents a sum. | |
107 | * @constructor | |
108 | * @param {number} num1 The first number. | |
109 | * @param {number} num2 The second number. | |
110 | */ | |
111 | function sum(num1, num2) { | |
112 | this.num1 = num1; | |
113 | this.num2 = num2; | |
114 | } | |
115 | ||
116 | // class constructor allows missing @returns tag | |
117 | /** | |
118 | * Represents a sum. | |
119 | */ | |
120 | class Sum { | |
121 | /** | |
122 | * @param {number} num1 The first number. | |
123 | * @param {number} num2 The second number. | |
124 | */ | |
125 | constructor(num1, num2) { | |
126 | this.num1 = num1; | |
127 | this.num2 = num2; | |
128 | } | |
129 | } | |
130 | ||
131 | // @abstract tag allows @returns tag without `return` statement | |
132 | class Widget { | |
133 | /** | |
134 | * When the state changes, does it affect the rendered appearance? | |
135 | * @abstract | |
136 | * @param {Object} state The new state of the widget. | |
137 | * @returns {boolean} Is current appearance inconsistent with new state? | |
138 | */ | |
139 | mustRender (state) { | |
140 | throw new Error("Widget subclass did not implement mustRender"); | |
141 | } | |
142 | } | |
143 | ||
144 | // @override tag allows missing @param and @returns tags | |
145 | class WonderfulWidget extends Widget { | |
146 | /** | |
147 | * @override | |
148 | */ | |
149 | mustRender (state) { | |
150 | return state !== this.state; // shallow comparison | |
151 | } | |
152 | } | |
153 | ``` | |
154 | ||
155 | ## Options | |
156 | ||
157 | This rule has an object option: | |
158 | ||
159 | * `"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`) | |
160 | * `"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`) | |
161 | * `"requireReturn"` requires a return tag: | |
162 | * `true` (default) **even if** the function or method does not have a `return` statement (this option value does not apply to constructors) | |
163 | * `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) | |
164 | * `"requireReturnType": false` allows missing type in return tags | |
165 | * `"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) | |
166 | * `"requireParamDescription": false` allows missing description in parameter tags | |
167 | * `"requireReturnDescription": false` allows missing description in return tags | |
168 | * `"requireParamType": false` allows missing type in parameter tags | |
169 | ||
170 | ### prefer | |
171 | ||
172 | Examples of additional **incorrect** code for this rule with sample `"prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }` options: | |
173 | ||
174 | ```js | |
175 | /*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/ | |
176 | /*eslint-env es6*/ | |
177 | ||
178 | /** | |
179 | * Add two numbers. | |
180 | * @arg {int} num1 The first number. | |
181 | * @arg {int} num2 The second number. | |
182 | * @return {int} The sum of the two numbers. | |
183 | */ | |
184 | function add(num1, num2) { | |
185 | return num1 + num2; | |
186 | } | |
187 | ||
188 | /** | |
189 | * Represents a sum. | |
190 | * @class | |
191 | * @argument {number} num1 The first number. | |
192 | * @argument {number} num2 The second number. | |
193 | */ | |
194 | function sum(num1, num2) { | |
195 | this.num1 = num1; | |
196 | this.num2 = num2; | |
197 | } | |
198 | ||
199 | class Widget { | |
200 | /** | |
201 | * When the state changes, does it affect the rendered appearance? | |
202 | * @virtual | |
203 | * @argument {Object} state The new state of the widget. | |
204 | * @return {boolean} Is current appearance inconsistent with new state? | |
205 | */ | |
206 | mustRender (state) { | |
207 | throw new Error("Widget subclass did not implement mustRender"); | |
208 | } | |
209 | } | |
210 | ``` | |
211 | ||
212 | ### preferType | |
213 | ||
214 | Examples of additional **incorrect** code for this rule with sample `"preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }` options: | |
215 | ||
216 | ```js | |
217 | /*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/ | |
218 | /*eslint-env es6*/ | |
219 | ||
220 | /** | |
221 | * Add two numbers. | |
222 | * @param {Number} num1 The first number. | |
223 | * @param {Number} num2 The second number. | |
224 | * @returns {Number} The sum of the two numbers. | |
225 | */ | |
226 | function add(num1, num2) { | |
227 | return num1 + num2; | |
228 | } | |
229 | ||
230 | /** | |
231 | * Output a greeting as a side effect. | |
232 | * @param {String} name Whom to greet. | |
233 | * @returns {void} | |
234 | */ | |
235 | function greet(name) { | |
236 | console.log("Hello " + name); | |
237 | } | |
238 | ||
239 | class Widget { | |
240 | /** | |
241 | * When the state changes, does it affect the rendered appearance? | |
242 | * @abstract | |
243 | * @param {object} state The new state of the widget. | |
244 | * @returns {Boolean} Is current appearance inconsistent with new state? | |
245 | */ | |
246 | mustRender (state) { | |
247 | throw new Error("Widget subclass did not implement mustRender"); | |
248 | } | |
249 | } | |
250 | ``` | |
251 | ||
252 | ### requireReturn | |
253 | ||
254 | Examples of additional **incorrect** code for this rule with the `"requireReturn": false` option: | |
255 | ||
256 | ```js | |
257 | /*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/ | |
258 | ||
259 | // unexpected @returns tag because function has no `return` statement | |
260 | /** | |
261 | * @param {string} name Whom to greet. | |
262 | * @returns {string} The greeting. | |
263 | */ | |
264 | function greet(name) { | |
265 | console.log("Hello " + name); | |
266 | } | |
267 | ||
268 | // add @abstract tag to allow @returns tag without `return` statement | |
269 | class Widget { | |
270 | /** | |
271 | * When the state changes, does it affect the rendered appearance? | |
272 | * @param {Object} state The new state of the widget. | |
273 | * @returns {boolean} Is current appearance inconsistent with new state? | |
274 | */ | |
275 | mustRender (state) { | |
276 | throw new Error("Widget subclass did not implement mustRender"); | |
277 | } | |
278 | } | |
279 | ``` | |
280 | ||
281 | Example of additional **correct** code for this rule with the `"requireReturn": false` option: | |
282 | ||
283 | ```js | |
284 | /*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/ | |
285 | ||
286 | /** | |
287 | * @param {string} name Whom to greet. | |
288 | */ | |
289 | function greet(name) { | |
290 | console.log("Hello " + name); | |
291 | } | |
292 | ``` | |
293 | ||
294 | ### requireReturnType | |
295 | ||
296 | Example of additional **correct** code for this rule with the `"requireReturnType": false` option: | |
297 | ||
298 | ```js | |
299 | /*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/ | |
300 | ||
301 | /** | |
302 | * Add two numbers. | |
303 | * @param {number} num1 The first number. | |
304 | * @param {number} num2 The second number. | |
305 | * @returns The sum of the two numbers. | |
306 | */ | |
307 | function add(num1, num2) { | |
308 | return num1 + num2; | |
309 | } | |
310 | ``` | |
311 | ||
312 | ### requireParamType | |
313 | ||
314 | Example of additional **correct** code for this rule with the `"requireParamType": false` option: | |
315 | ||
316 | ```js | |
317 | /*eslint valid-jsdoc: ["error", { "requireParamType": false }]*/ | |
318 | ||
319 | /** | |
320 | * Add two numbers. | |
321 | * @param num1 The first number. | |
322 | * @param num2 The second number. | |
323 | * @returns {number} The sum of the two numbers. | |
324 | */ | |
325 | function add(num1, num2) { | |
326 | return num1 + num2; | |
327 | } | |
328 | ``` | |
329 | ||
330 | ### matchDescription | |
331 | ||
332 | Example of additional **incorrect** code for this rule with a sample `"matchDescription": ".+"` option: | |
333 | ||
334 | ```js | |
335 | /*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/ | |
336 | ||
337 | // missing function description | |
338 | /** | |
339 | * @param {string} name Whom to greet. | |
340 | * @returns {void} | |
341 | */ | |
342 | function greet(name) { | |
343 | console.log("Hello " + name); | |
344 | } | |
345 | ``` | |
346 | ||
347 | ### requireParamDescription | |
348 | ||
349 | Example of additional **correct** code for this rule with the `"requireParamDescription": false` option: | |
350 | ||
351 | ```js | |
352 | /*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/ | |
353 | ||
354 | /** | |
355 | * Add two numbers. | |
356 | * @param {int} num1 | |
357 | * @param {int} num2 | |
358 | * @returns {int} The sum of the two numbers. | |
359 | */ | |
360 | function add(num1, num2) { | |
361 | return num1 + num2; | |
362 | } | |
363 | ``` | |
364 | ||
365 | ### requireReturnDescription | |
366 | ||
367 | Example of additional **correct** code for this rule with the `"requireReturnDescription": false` option: | |
368 | ||
369 | ```js | |
370 | /*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/ | |
371 | ||
372 | /** | |
373 | * Add two numbers. | |
374 | * @param {number} num1 The first number. | |
375 | * @param {number} num2 The second number. | |
376 | * @returns {number} | |
377 | */ | |
378 | function add(num1, num2) { | |
379 | return num1 + num2; | |
380 | } | |
381 | ``` | |
382 | ||
383 | ## When Not To Use It | |
384 | ||
385 | If you aren't using JSDoc, then you can safely turn this rule off. | |
386 | ||
387 | ## Further Reading | |
388 | ||
389 | * [JSDoc](http://usejsdoc.org) | |
390 | ||
391 | ## Related Rules | |
392 | ||
393 | * [require-jsdoc](require-jsdoc.md) |