eslint/docs/src/rules/valid-jsdoc.md

   1 ---
   2 title: valid-jsdoc
   3 rule_type: suggestion
   4 related_rules:
   5 - require-jsdoc
   6 further_reading:
   7 - https://jsdoc.app
   8 ---
   9
  10
  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
  49 ::: incorrect
  50
  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
  89 :::
  90
  91 Examples of **correct** code for this rule:
  92
  93 ::: correct
  94
  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
 170 :::
 171
 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
 191 ::: incorrect
 192
 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
 231 :::
 232
 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
 237 ::: incorrect
 238
 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
 275 :::
 276
 277 ### requireReturn
 278
 279 Examples of additional **incorrect** code for this rule with the `"requireReturn": false` option:
 280
 281 ::: incorrect
 282
 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
 308 :::
 309
 310 Example of additional **correct** code for this rule with the `"requireReturn": false` option:
 311
 312 ::: correct
 313
 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
 325 :::
 326
 327 ### requireReturnType
 328
 329 Example of additional **correct** code for this rule with the `"requireReturnType": false` option:
 330
 331 ::: correct
 332
 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
 347 :::
 348
 349 ### requireParamType
 350
 351 Example of additional **correct** code for this rule with the `"requireParamType": false` option:
 352
 353 ::: correct
 354
 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
 369 :::
 370
 371 ### matchDescription
 372
 373 Example of additional **incorrect** code for this rule with a sample `"matchDescription": ".+"` option:
 374
 375 ::: incorrect
 376
 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
 390 :::
 391
 392 ### requireParamDescription
 393
 394 Example of additional **correct** code for this rule with the `"requireParamDescription": false` option:
 395
 396 ::: correct
 397
 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
 412 :::
 413
 414 ### requireReturnDescription
 415
 416 Example of additional **correct** code for this rule with the `"requireReturnDescription": false` option:
 417
 418 ::: correct
 419
 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
 434 :::
 435
 436 ## When Not To Use It
 437
 438 If you aren't using JSDoc, then you can safely turn this rule off.