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