feat: Add checkJSDoc option to multiline-comment-style (#16807)

laurent22 · mdjermanovic · web-flow · commit c89a485c4945 · 2023-03-08T09:51:14.000+01:00
* feat: Add support for checkJSDoc param for "multiline-comment-style"

* Update lib/rules/multiline-comment-style.js

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* Apply suggestions from code review

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* Update docs/src/rules/multiline-comment-style.md

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

---------

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;
diff --git 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
@@ -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
@@ -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
