feat(require-hyphen-before-param-description): when always is set, disallow hyphen at end of line; fixes #1435 (#1454)

Author: brettz9

.README/rules/require-hyphen-before-param-description.md

@@ -6,7 +6,7 @@ Requires (or disallows) a hyphen before the `@param` description.
 
 ## Fixer
 
-(Todo)
+Adds a hyphen for "always" and removes a hyphen for "never".
 
 ## Options
 
@@ -16,6 +16,11 @@ If the string is `"always"` then a problem is raised when there is no hyphen
 before the description. If it is `"never"` then a problem is raised when there
 is a hyphen before the description. The default value is `"always"`.
 
+Even if hyphens are set to "always" appear after the tag name, they will
+actually be forbidden in the event that they are followed immediately by
+the end of a line (this will otherwise cause Visual Studio Code to display
+incorrectly).
+
 The options object may have the following properties to indicate behavior for
 other tags besides the `@param` tag (or the `@arg` tag if so set):
 

docs/rules/require-hyphen-before-param-description.md

@@ -15,7 +15,7 @@ Requires (or disallows) a hyphen before the `@param` description.
 <a name="require-hyphen-before-param-description-fixer"></a>
 ## Fixer
 
-(Todo)
+Adds a hyphen for "always" and removes a hyphen for "never".
 
 <a name="user-content-require-hyphen-before-param-description-options"></a>
 <a name="require-hyphen-before-param-description-options"></a>
@@ -27,6 +27,11 @@ If the string is `"always"` then a problem is raised when there is no hyphen
 before the description. If it is `"never"` then a problem is raised when there
 is a hyphen before the description. The default value is `"always"`.
 
+Even if hyphens are set to "always" appear after the tag name, they will
+actually be forbidden in the event that they are followed immediately by
+the end of a line (this will otherwise cause Visual Studio Code to display
+incorrectly).
+
 The options object may have the following properties to indicate behavior for
 other tags besides the `@param` tag (or the `@arg` tag if so set):
 
@@ -202,6 +207,14 @@ function quux () {
  */
 function test(input) {}
 // Message: There must be a hyphen before @param description.
+
+/**
+ * @param foo -
+ * The possible values for `foo` are as follows.
+ * - `"option1"`: Description of option 1.
+ * - `"option2"`: Description of option 2.
+ */
+// Message: There must be no hyphen followed by newline after the @param name.
 ````
 
 
@@ -294,5 +307,24 @@ function main(argv) {
  * @typedef {any} Test
  */
 // "jsdoc/require-hyphen-before-param-description": ["error"|"warn", "always",{"tags":{"template":"always"}}]
+
+/**
+ * @param foo - The possible values for `foo` are as follows.
+ * - `"option1"`: Description of option 1.
+ * - `"option2"`: Description of option 2.
+ */
+
+/**
+ * @param foo
+ * The possible values for `foo` are as follows.
+ * - `"option1"`: Description of option 1.
+ * - `"option2"`: Description of option 2.
+ */
+
+/**
+ * @param foo
+ * - `"option1"`: Description of option 1.
+ * - `"option2"`: Description of option 2.
+ */
 ````
 

src/rules/requireHyphenBeforeParamDescription.js

@@ -30,6 +30,8 @@ export default iterateJsdoc(({
     }
 
     const startsWithHyphen = (/^\s*-/v).test(desc);
+    const hyphenNewline = (/^\s*-\n/v).test(desc);
+
     let lines = 0;
     for (const {
       tokens,
@@ -41,30 +43,41 @@ export default iterateJsdoc(({
       lines++;
     }
 
-    if (always) {
+    if (always && !hyphenNewline) {
       if (!startsWithHyphen) {
-        utils.reportJSDoc(
-          `There must be a hyphen before @${targetTagName} description.`,
-          {
-            line: jsdocTag.source[0].number + lines,
-          },
-          () => {
-            for (const {
-              tokens,
-            } of jsdocTag.source) {
-              if (tokens.description) {
-                tokens.description = tokens.description.replace(
-                  /^(\s*)/v, '$1- ',
-                );
-                break;
-              }
-            }
-          },
-        );
+        let fixIt = true;
+        for (const {
+          tokens,
+        } of jsdocTag.source) {
+          if (tokens.description) {
+            tokens.description = tokens.description.replace(
+              /^(\s*)/v, '$1- ',
+            );
+            break;
+          }
+
+          // Linebreak after name since has no description
+          if (tokens.name) {
+            fixIt = false;
+            break;
+          }
+        }
+
+        if (fixIt) {
+          utils.reportJSDoc(
+            `There must be a hyphen before @${targetTagName} description.`,
+            {
+              line: jsdocTag.source[0].number + lines,
+            },
+            () => {},
+          );
+        }
       }
     } else if (startsWithHyphen) {
       utils.reportJSDoc(
-        `There must be no hyphen before @${targetTagName} description.`,
+        always ?
+          `There must be no hyphen followed by newline after the @${targetTagName} name.` :
+          `There must be no hyphen before @${targetTagName} description.`,
         {
           line: jsdocTag.source[0].number + lines,
         },
@@ -76,6 +89,10 @@ export default iterateJsdoc(({
               tokens.description = tokens.description.replace(
                 /^\s*-\s*/v, '',
               );
+              if (hyphenNewline) {
+                tokens.postName = '';
+              }
+
               break;
             }
           }

test/rules/assertions/requireHyphenBeforeParamDescription.js

@@ -496,6 +496,30 @@ export default /** @type {import('../index.js').TestCases} */ ({
         function test(name) {}
       `,
     },
+    {
+      code: `
+        /**
+         * @param foo -
+         * The possible values for \`foo\` are as follows.
+         * - \`"option1"\`: Description of option 1.
+         * - \`"option2"\`: Description of option 2.
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'There must be no hyphen followed by newline after the @param name.',
+        },
+      ],
+      output: `
+        /**
+         * @param foo
+         * The possible values for \`foo\` are as follows.
+         * - \`"option1"\`: Description of option 1.
+         * - \`"option2"\`: Description of option 2.
+         */
+      `,
+    },
   ],
   valid: [
     {
@@ -658,5 +682,33 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * @param foo - The possible values for \`foo\` are as follows.
+         * - \`"option1"\`: Description of option 1.
+         * - \`"option2"\`: Description of option 2.
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param foo
+         * The possible values for \`foo\` are as follows.
+         * - \`"option1"\`: Description of option 1.
+         * - \`"option2"\`: Description of option 2.
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param foo
+         * - \`"option1"\`: Description of option 1.
+         * - \`"option2"\`: Description of option 2.
+         */
+      `,
+    },
   ],
 });