eslint/docs/rules/multiline-comment-style.md

   1 # enforce a particular style for multiline comments (multiline-comment-style)
   2
   3 Many style guides require a particular style for comments that span multiple lines. For example, some style guides prefer the use of a single block comment for multiline comments, whereas other style guides prefer consecutive line comments.
   4
   5 ## Rule Details
   6
   7 This rule aims to enforce a particular style for multiline comments.
   8
   9 ### Options
  10
  11 This rule has a string option, which can have one of the following values:
  12
  13 * `"starred-block"` (default): Disallows consecutive line comments in favor of block comments. Additionally, requires block comments to have an aligned `*` character before each line.
  14 * `"bare-block"`: Disallows consecutive line comments in favor of block comments, and disallows block comments from having a `"*"` character before each line.
  15 * `"separate-lines"`: Disallows block comments in favor of consecutive line comments
  16
  17 The rule always ignores directive comments such as `/* eslint-disable */`. Additionally, unless the mode is `"starred-block"`, the rule ignores JSDoc comments.
  18
  19 Examples of **incorrect** code for this rule with the default `"starred-block"` option:
  20
  21 ```js
  22
  23 /* eslint multiline-comment-style: ["error", "starred-block"] */
  24
  25 // this line
  26 // calls foo()
  27 foo();
  28
  29 /* this line
  30 calls foo() */
  31 foo();
  32
  33 /* this comment
  34  * is missing a newline after /*
  35  */
  36
  37 /*
  38  * this comment
  39  * is missing a newline at the end */
  40
  41 /*
  42 * the star in this line should have a space before it
  43  */
  44
  45 /*
  46  * the star on the following line should have a space before it
  47 */
  48
  49 ```
  50
  51 Examples of **correct** code for this rule with the default `"starred-block"` option:
  52
  53 ```js
  54 /* eslint multiline-comment-style: ["error", "starred-block"] */
  55
  56 /*
  57  * this line
  58  * calls foo()
  59  */
  60 foo();
  61
  62 // single-line comment
  63 ```
  64
  65 Examples of **incorrect** code for this rule with the `"bare-block"` option:
  66
  67 ```js
  68 /* eslint multiline-comment-style: ["error", "bare-block"] */
  69
  70 // this line
  71 // calls foo()
  72 foo();
  73
  74 /*
  75  * this line
  76  * calls foo()
  77  */
  78 foo();
  79 ```
  80
  81 Examples of **correct** code for this rule with the `"bare-block"` option:
  82
  83 ```js
  84 /* eslint multiline-comment-style: ["error", "bare-block"] */
  85
  86 /* this line
  87    calls foo() */
  88 foo();
  89 ```
  90
  91 Examples of **incorrect** code for this rule with the `"separate-lines"` option:
  92
  93 ```js
  94
  95 /* eslint multiline-comment-style: ["error", "separate-lines"] */
  96
  97 /* This line
  98 calls foo() */
  99 foo();
 100
 101 /*
 102  * This line
 103  * calls foo()
 104  */
 105 foo();
 106
 107 ```
 108
 109 Examples of **correct** code for this rule with the `"separate-lines"` option:
 110
 111 ```js
 112 /* eslint multiline-comment-style: ["error", "separate-lines"] */
 113
 114 // This line
 115 // calls foo()
 116 foo();
 117
 118
 119 ```
 120
 121 ## When Not To Use It
 122
 123 If you don't want to enforce a particular style for multiline comments, you can disable the rule.