diff --git a/docs/src/rules/multiline-comment-style.md b/docs/src/rules/multiline-comment-style.md index 2113389d94c..28e6648ad03 100644 --- a/docs/src/rules/multiline-comment-style.md +++ b/docs/src/rules/multiline-comment-style.md @@ -16,10 +16,10 @@ This rule aims to enforce a particular style for multiline comments. This rule has a string option, which can have one of the following values: * `"starred-block"` (default): Disallows consecutive line comments in favor of block comments. Additionally, requires block comments to have an aligned `*` character before each line. -* `"bare-block"`: Disallows consecutive line comments in favor of block comments, and disallows block comments from having a `"*"` character before each line. -* `"separate-lines"`: Disallows block comments in favor of consecutive line comments +* `"bare-block"`: Disallows consecutive line comments in favor of block comments, and disallows block comments from having a `"*"` character before each line. This option ignores JSDoc comments. +* `"separate-lines"`: Disallows block comments in favor of consecutive line comments. By default, this option ignores JSDoc comments. To also apply this rule to JSDoc comments, set the `checkJSDoc` option to `true`. -The rule always ignores directive comments such as `/* eslint-disable */`. Additionally, unless the mode is `"starred-block"`, the rule ignores JSDoc comments. +The rule always ignores directive comments such as `/* eslint-disable */`. Examples of **incorrect** code for this rule with the default `"starred-block"` option: @@ -146,6 +146,39 @@ foo(); ::: +Examples of **incorrect** code for this rule with the `"separate-lines"` option and `checkJSDoc` set to `true`: + +::: incorrect + +```js + +/* eslint multiline-comment-style: ["error", "separate-lines", { "checkJSDoc": true }] */ + +/** + * I am a JSDoc comment + * and I'm not allowed + */ +foo(); + +``` + +::: + +Examples of **correct** code for this rule with the `"separate-lines"` option and `checkJSDoc` set to `true`: + +::: correct + +```js +/* eslint multiline-comment-style: ["error", "separate-lines", { "checkJSDoc": true }] */ + +// I am a JSDoc comment +// and I'm not allowed +foo(); + +``` + +::: + ## When Not To Use It If you don't want to enforce a particular style for multiline comments, you can disable the rule. diff --git a/lib/rules/multiline-comment-style.js b/lib/rules/multiline-comment-style.js index 68cd666532d..9cb7f3473e5 100644 --- a/lib/rules/multiline-comment-style.js +++ b/lib/rules/multiline-comment-style.js @@ -22,7 +22,37 @@ module.exports = { }, fixable: "whitespace", - schema: [{ enum: ["starred-block", "separate-lines", "bare-block"] }], + schema: { + anyOf: [ + { + type: "array", + items: [ + { + enum: ["starred-block", "bare-block"] + } + ], + additionalItems: false + }, + { + type: "array", + items: [ + { + enum: ["separate-lines"] + }, + { + type: "object", + properties: { + checkJSDoc: { + type: "boolean" + } + }, + additionalProperties: false + } + ], + additionalItems: false + } + ] + }, messages: { expectedBlock: "Expected a block comment instead of consecutive line comments.", expectedBareBlock: "Expected a block comment without padding stars.", @@ -37,6 +67,8 @@ module.exports = { create(context) { const sourceCode = context.getSourceCode(); const option = context.options[0] || "starred-block"; + const params = context.options[1] || {}; + const checkJSDoc = !!params.checkJSDoc; //---------------------------------------------------------------------- // Helpers @@ -333,11 +365,18 @@ module.exports = { "separate-lines"(commentGroup) { const [firstComment] = commentGroup; - if (firstComment.type !== "Block" || isJSDocComment(commentGroup)) { + const isJSDoc = isJSDocComment(commentGroup); + + if (firstComment.type !== "Block" || (!checkJSDoc && isJSDoc)) { return; } - const commentLines = getCommentLines(commentGroup); + let commentLines = getCommentLines(commentGroup); + + if (isJSDoc) { + commentLines = commentLines.slice(1, commentLines.length - 1); + } + const tokenAfter = sourceCode.getTokenAfter(firstComment, { includeComments: true }); if (tokenAfter && firstComment.loc.end.line === tokenAfter.loc.start.line) { diff --git a/tests/lib/rules/multiline-comment-style.js b/tests/lib/rules/multiline-comment-style.js index 1f2302f9a22..a127d7ec4cb 100644 --- a/tests/lib/rules/multiline-comment-style.js +++ b/tests/lib/rules/multiline-comment-style.js @@ -628,6 +628,20 @@ ruleTester.run("multiline-comment-style", rule, { options: ["separate-lines"], errors: [{ messageId: "expectedLines", line: 2 }] }, + { + code: ` + /** + * JSDoc + * Comment + */ + `, + output: ` + // JSDoc + // Comment + `, + options: ["separate-lines", { checkJSDoc: true }], + errors: [{ messageId: "expectedLines", line: 2 }] + }, { code: ` /* foo