From b119081eb75ad8109071dc65ab675a0ee01967a4 Mon Sep 17 00:00:00 2001 From: Laurent Cozic Date: Tue, 7 Mar 2023 10:10:22 +0000 Subject: [PATCH 1/4] feat: Add support for checkJSDoc param for "multiline-comment-style" --- docs/src/rules/multiline-comment-style.md | 37 ++++++++++++++++++++-- lib/rules/multiline-comment-style.js | 29 +++++++++++++++-- tests/lib/rules/multiline-comment-style.js | 14 ++++++++ 3 files changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/src/rules/multiline-comment-style.md b/docs/src/rules/multiline-comment-style.md index 2113389d94c..e658a43c1e8 100644 --- a/docs/src/rules/multiline-comment-style.md +++ b/docs/src/rules/multiline-comment-style.md @@ -17,9 +17,9 @@ 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 +* `"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..73c6697e67d 100644 --- a/lib/rules/multiline-comment-style.js +++ b/lib/rules/multiline-comment-style.js @@ -22,7 +22,21 @@ module.exports = { }, fixable: "whitespace", - schema: [{ enum: ["starred-block", "separate-lines", "bare-block"] }], + schema: [ + { + enum: ["starred-block", "separate-lines", "bare-block"] + }, + { + type: "object", + properties: { + checkJSDoc: { + type: "boolean", + default: false + } + }, + additionalProperties: false + } + ], messages: { expectedBlock: "Expected a block comment instead of consecutive line comments.", expectedBareBlock: "Expected a block comment without padding stars.", @@ -37,6 +51,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 +349,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 (checkJSDoc && 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 From 22abcf407c4458566c02785b157d3452018c38d6 Mon Sep 17 00:00:00 2001 From: Laurent Cozic Date: Tue, 7 Mar 2023 16:54:42 +0000 Subject: [PATCH 2/4] Update lib/rules/multiline-comment-style.js Co-authored-by: Milos Djermanovic --- lib/rules/multiline-comment-style.js | 44 +++++++++++++++++++--------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/lib/rules/multiline-comment-style.js b/lib/rules/multiline-comment-style.js index 73c6697e67d..5ab094d918d 100644 --- a/lib/rules/multiline-comment-style.js +++ b/lib/rules/multiline-comment-style.js @@ -22,21 +22,37 @@ module.exports = { }, fixable: "whitespace", - schema: [ - { - enum: ["starred-block", "separate-lines", "bare-block"] - }, - { - type: "object", - properties: { - checkJSDoc: { - type: "boolean", - default: false - } + schema: { + anyOf: [ + { + type: "array", + items: [ + { + enum: ["starred-block", "bare-block"] + } + ], + additionalItems: false }, - additionalProperties: 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.", From 0427eea3bdc77dc59208e44b37e887618b549b26 Mon Sep 17 00:00:00 2001 From: Laurent Cozic Date: Tue, 7 Mar 2023 16:57:51 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Milos Djermanovic --- lib/rules/multiline-comment-style.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/rules/multiline-comment-style.js b/lib/rules/multiline-comment-style.js index 5ab094d918d..9cb7f3473e5 100644 --- a/lib/rules/multiline-comment-style.js +++ b/lib/rules/multiline-comment-style.js @@ -373,7 +373,7 @@ module.exports = { let commentLines = getCommentLines(commentGroup); - if (checkJSDoc && isJSDoc) { + if (isJSDoc) { commentLines = commentLines.slice(1, commentLines.length - 1); } From ccd1f12d1fe43573dedf0efe66dc8f521dc61779 Mon Sep 17 00:00:00 2001 From: Laurent Cozic Date: Tue, 7 Mar 2023 16:58:09 +0000 Subject: [PATCH 4/4] Update docs/src/rules/multiline-comment-style.md Co-authored-by: Milos Djermanovic --- docs/src/rules/multiline-comment-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/rules/multiline-comment-style.md b/docs/src/rules/multiline-comment-style.md index e658a43c1e8..28e6648ad03 100644 --- a/docs/src/rules/multiline-comment-style.md +++ b/docs/src/rules/multiline-comment-style.md @@ -16,7 +16,7 @@ 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. +* `"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 */`.