feat(no-multi-asterisks): add allowWhitespace option; fixes #803

gajus · Dec 31, 2021 · 6ddc79c · 6ddc79c
1 parent f308667
commit 6ddc79c
Show file tree

Hide file tree

Showing 4 changed files with 202 additions and 6 deletions.
diff --git a/.README/rules/no-multi-asterisks.md b/.README/rules/no-multi-asterisks.md
@@ -8,6 +8,16 @@ and that rule is for catching blocks which only seem like jsdoc).
 
 #### Options
 
+##### `allowWhitespace` (defaults to `false`)
+
+Set to `true` if you wish to allow asterisks after a space (as with Markdown):
+
+```js
+/**
+ * *bold* text
+ */
+```
+
 ##### `preventAtMiddleLines` (defaults to `true`)
 
 Prevent the likes of this:

diff --git a/README.md b/README.md
@@ -8712,6 +8712,17 @@ and that rule is for catching blocks which only seem like jsdoc).
 <a name="eslint-plugin-jsdoc-rules-no-multi-asterisks-options-18"></a>
 #### Options
 
+<a name="eslint-plugin-jsdoc-rules-no-multi-asterisks-options-18-allowwhitespace-defaults-to-false"></a>
+##### <code>allowWhitespace</code> (defaults to <code>false</code>)
+
+Set to `true` if you wish to allow asterisks after a space (as with Markdown):
+
+```js
+/**
+ * *bold* text
+ */
+```
+
 <a name="eslint-plugin-jsdoc-rules-no-multi-asterisks-options-18-preventatmiddlelines-defaults-to-true"></a>
 ##### <code>preventAtMiddleLines</code> (defaults to <code>true</code>)
 
@@ -8823,6 +8834,25 @@ The following patterns are considered problems:
  * */
 // "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}]
 // Message: Should be no multiple asterisks on end lines.
+
+/**
+ * The method does 2 things:
+ * * Thing 1
+ * * Thing 2
+ */
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}]
+// Message: Should be no multiple asterisks on middle lines.
+
+/**
+ * This muti-line comment contains some
+ * *non-standard bold* syntax
+ */
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}]
+// Message: Should be no multiple asterisks on middle lines.
+
+/** Desc. **/
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
+// Message: Should be no multiple asterisks on end lines.
 ````
 
 The following patterns are not considered problems:
@@ -8900,6 +8930,25 @@ function foo() {
  *
  * **Bold example:** Hi there.
  */
+
+/**
+ * The method does 2 things:
+ * * Thing 1
+ * * Thing 2
+ */
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
+
+/**
+ * This muti-line comment contains some
+ * *non-standard bold* syntax
+ */
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
+
+/** abc */
+function foo() {
+    //
+}
+// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
 ````
 
 

diff --git a/src/rules/noMultiAsterisks.js b/src/rules/noMultiAsterisks.js
@@ -1,17 +1,28 @@
 import iterateJsdoc from '../iterateJsdoc';
 
-const middleAsterisks = /^([\t ]|\*(?!\*))+/u;
+const middleAsterisksBlockWS = /^([\t ]|\*(?!\*))+/u;
+const middleAsterisksNoBlockWS = /^\*+/u;
+
+const endAsterisksSingleLineBlockWS = /\*((?:\*|(?: |\t))*)\*$/u;
+const endAsterisksMultipleLineBlockWS = /((?:\*|(?: |\t))*)\*$/u;
+
+const endAsterisksSingleLineNoBlockWS = /\*(\**)\*$/u;
+const endAsterisksMultipleLineNoBlockWS = /(\**)\*$/u;
 
 export default iterateJsdoc(({
   context,
   jsdoc,
   utils,
 }) => {
   const {
+    allowWhitespace = false,
     preventAtEnd = true,
     preventAtMiddleLines = true,
   } = context.options[0] || {};
 
+  const middleAsterisks = allowWhitespace ? middleAsterisksNoBlockWS : middleAsterisksBlockWS;
+
+  // eslint-disable-next-line complexity -- Todo
   jsdoc.source.some(({
     tokens,
     number,
@@ -23,11 +34,18 @@ export default iterateJsdoc(({
       type,
       description,
       end,
+      postDelimiter,
     } = tokens;
+
     if (
       preventAtMiddleLines &&
-      !end && !tag && !type && !name && middleAsterisks.test(description)
+      !end && !tag && !type && !name &&
+      (
+        !allowWhitespace && middleAsterisks.test(description) ||
+        allowWhitespace && middleAsterisks.test(postDelimiter + description)
+      )
     ) {
+      // console.log('description', JSON.stringify(description));
       const fix = () => {
         tokens.description = description.replace(middleAsterisks, '');
       };
@@ -50,11 +68,16 @@ export default iterateJsdoc(({
 
     const isSingleLineBlock = delimiter === '/**';
     const delim = isSingleLineBlock ? '*' : delimiter;
-    const endAsterisks = isSingleLineBlock ?
-      /\*((?:\*|(?: |\t))*)\*$/u :
-      /((?:\*|(?: |\t))*)\*$/u;
+    let endAsterisks;
+    if (allowWhitespace) {
+      endAsterisks = isSingleLineBlock ? endAsterisksSingleLineNoBlockWS : endAsterisksMultipleLineNoBlockWS;
+    } else {
+      endAsterisks = isSingleLineBlock ? endAsterisksSingleLineBlockWS : endAsterisksMultipleLineBlockWS;
+    }
 
-    const endingAsterisksAndSpaces = (description + delim).match(
+    const endingAsterisksAndSpaces = (
+      allowWhitespace ? postDelimiter + description + delim : description + delim
+    ).match(
       endAsterisks,
     );
 
@@ -96,6 +119,9 @@ export default iterateJsdoc(({
       {
         additionalProperies: false,
         properties: {
+          allowWhitespace: {
+            type: 'boolean',
+          },
           preventAtEnd: {
             type: 'boolean',
           },

diff --git a/test/rules/assertions/noMultiAsterisks.js b/test/rules/assertions/noMultiAsterisks.js
@@ -276,6 +276,77 @@ export default {
         */
       `,
     },
+    {
+      code: `
+      /**
+       * The method does 2 things:
+       * * Thing 1
+       * * Thing 2
+       */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'Should be no multiple asterisks on middle lines.',
+        },
+      ],
+      options: [
+        {
+          allowWhitespace: false,
+        },
+      ],
+      output: `
+      /**
+       * The method does 2 things:
+       * Thing 1
+       * * Thing 2
+       */
+      `,
+    },
+    {
+      code: `
+      /**
+       * This muti-line comment contains some
+       * *non-standard bold* syntax
+       */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'Should be no multiple asterisks on middle lines.',
+        },
+      ],
+      options: [
+        {
+          allowWhitespace: false,
+        },
+      ],
+      output: `
+      /**
+       * This muti-line comment contains some
+       * non-standard bold* syntax
+       */
+      `,
+    },
+    {
+      code: `
+      /** Desc. **/
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Should be no multiple asterisks on end lines.',
+        },
+      ],
+      options: [
+        {
+          allowWhitespace: true,
+        },
+      ],
+      output: `
+      /** Desc. */
+      `,
+    },
   ],
   valid: [
     {
@@ -402,5 +473,45 @@ export default {
        */
       `,
     },
+    {
+      code: `
+      /**
+       * The method does 2 things:
+       * * Thing 1
+       * * Thing 2
+       */
+      `,
+      options: [
+        {
+          allowWhitespace: true,
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * This muti-line comment contains some
+       * *non-standard bold* syntax
+       */
+      `,
+      options: [
+        {
+          allowWhitespace: true,
+        },
+      ],
+    },
+    {
+      code: `
+      /** abc */
+      function foo() {
+          //
+      }
+      `,
+      options: [
+        {
+          allowWhitespace: true,
+        },
+      ],
+    },
   ],
 };