multiline-comment-style

为多行注释强制执行特定样式

许多风格指南对跨多行的注释要求特定的风格。例如，一些风格指南更喜欢使用单个块注释来处理多行注释，而其他风格指南则更喜欢连续的行注释。

🌐 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.

规则详情

🌐 Rule Details

此规则旨在为多行注释强制执行特定样式。

🌐 This rule aims to enforce a particular style for multiline comments.

选项

🌐 Options

此规则有一个字符串选项，它可以具有以下值之一：

🌐 This rule has a string option, which can have one of the following values:

• "starred-block"（默认）：不允许连续的行注释，而是使用块注释。此外，要求块注释在每行之前都有对齐的 * 字符。
• "bare-block"：禁止连续的行注释，建议使用块注释，并且禁止块注释在每行前面有 "*" 字符。此选项会忽略 JSDoc 注释。
• "separate-lines"：禁止使用块注释，而提倡连续行注释。默认情况下，此选项会忽略 JSDoc 注释。若要将此规则也应用于 JSDoc 注释，请将 checkJSDoc 选项设置为 true。

该规则总是忽略诸如 /* eslint-disable */ 的指令性注释。

🌐 The rule always ignores directive comments such as /* eslint-disable */.

使用默认 "starred-block" 选项时，该规则的错误代码示例：

🌐 Examples of incorrect code for this rule with the default "starred-block" option:

/* eslint multiline-comment-style: ["error", "starred-block"] */

// this line
// calls foo()
foo();

/* this line
calls foo() */
foo();

/* this comment
 * is missing a newline after /*
 */

/*
 * this comment
 * is missing a newline at the end */

/*
* the star in this line should have a space before it
 */

/*
 * the star on the following line should have a space before it
*/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

使用默认 "starred-block" 选项时，该规则的正确代码示例：

🌐 Examples of correct code for this rule with the default "starred-block" option:

/* eslint multiline-comment-style: ["error", "starred-block"] */

/*
 * this line
 * calls foo()
 */
foo();

// single-line comment
1
2
3
4
5
6
7
8
9

使用 "bare-block" 选项时违反此规则的错误代码示例：

🌐 Examples of incorrect code for this rule with the "bare-block" option:

/* eslint multiline-comment-style: ["error", "bare-block"] */

// this line
// calls foo()
foo();

/*
 * this line
 * calls foo()
 */
foo();
1
2
3
4
5
6
7
8
9
10
11

使用 "bare-block" 选项时，此规则的正确代码示例：

🌐 Examples of correct code for this rule with the "bare-block" option:

/* eslint multiline-comment-style: ["error", "bare-block"] */

/* this line
   calls foo() */
foo();
1
2
3
4
5

使用 "separate-lines" 选项时违反此规则的错误代码示例：

🌐 Examples of incorrect code for this rule with the "separate-lines" option:

/* eslint multiline-comment-style: ["error", "separate-lines"] */

/* This line
calls foo() */
foo();

/*
 * This line
 * calls foo()
 */
foo();

1
2
3
4
5
6
7
8
9
10
11
12
13

使用 "separate-lines" 选项时，此规则的正确代码示例：

🌐 Examples of correct code for this rule with the "separate-lines" option:

/* eslint multiline-comment-style: ["error", "separate-lines"] */

// This line
// calls foo()
foo();

1
2
3
4
5
6

使用 "separate-lines" 选项且 checkJSDoc 设置为 true 时，此规则的错误代码示例：

🌐 Examples of incorrect code for this rule with the "separate-lines" option and checkJSDoc set to true:

/* eslint multiline-comment-style: ["error", "separate-lines", { "checkJSDoc": true }] */

/**
 * I am a JSDoc comment
 * and I'm not allowed
 */
foo();

1
2
3
4
5
6
7
8
9

使用 "separate-lines" 选项且 checkJSDoc 设置为 true 时，此规则的正确代码示例：

🌐 Examples of correct code for this rule with the "separate-lines" option and checkJSDoc set to true:

/* eslint multiline-comment-style: ["error", "separate-lines", { "checkJSDoc": true }] */

// I am a JSDoc comment
// and I'm not allowed
foo();

1
2
3
4
5
6

何时不使用

🌐 When Not To Use It

如果你不想为多行注释强制执行特定样式，则可以禁用该规则。

🌐 If you don’t want to enforce a particular style for multiline comments, you can disable the rule.

版本

此规则是在 ESLint v4.10.0 中引入。

资源

• 规则源码
• 测试源码