From 52119a59e70d2d255e0f475f0fcd0bf780d0acd2 Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Thu, 11 May 2023 00:35:40 +0800
Subject: [PATCH] fix(`require-hyphen-before-param-description`): more targeted
 replacement for hyphen removal; fixes #1074 (#1075)

---
 ...require-hyphen-before-param-description.md | 23 ++++++
 .../requireHyphenBeforeParamDescription.js    | 37 ++++++---
 .../requireHyphenBeforeParamDescription.js    | 77 ++++++++++++++++++-
 3 files changed, 127 insertions(+), 10 deletions(-)

diff --git a/docs/rules/require-hyphen-before-param-description.md b/docs/rules/require-hyphen-before-param-description.md
index ff4a8ede9..288eea5a3 100644
--- a/docs/rules/require-hyphen-before-param-description.md
+++ b/docs/rules/require-hyphen-before-param-description.md
@@ -170,6 +170,29 @@ function quux () {
 }
 // "jsdoc/require-hyphen-before-param-description": ["error"|"warn", "always",{"tags":{"returns":"never"}}]
 // Message: There must be a hyphen before @param description.
+
+/**
+ * Split a unit to metric prefix and basic unit.
+ *
+ * @param {string} unit - Unit to split.
+ * @param {string} [basicUnit] - Basic unit regardless of the metric prefix.
+ *     If omitted, basic unit will be inferred by trying to remove the metric
+ *     prefix in `unit`.
+ *
+ * @returns {{ prefix: string, basicUnit: string }} - Split result.
+ *     If `unit` does not have a metric prefix, `''` is returned for `prefix`.
+ *     If `unit` does not have a basic unit, `''` is returned for `basicUnit`.
+ */
+// "jsdoc/require-hyphen-before-param-description": ["error"|"warn", "always",{"tags":{"*":"never","property":"always"}}]
+// Message: There must be no hyphen before @returns description.
+
+/**
+ * @returns {{
+ *   prefix: string, basicUnit: string
+ * }} - Split result.
+ */
+// "jsdoc/require-hyphen-before-param-description": ["error"|"warn", "always",{"tags":{"*":"never","property":"always"}}]
+// Message: There must be no hyphen before @returns description.
 ````
 
 
diff --git a/src/rules/requireHyphenBeforeParamDescription.js b/src/rules/requireHyphenBeforeParamDescription.js
index 811fb661e..2241f59b6 100644
--- a/src/rules/requireHyphenBeforeParamDescription.js
+++ b/src/rules/requireHyphenBeforeParamDescription.js
@@ -42,17 +42,36 @@ export default iterateJsdoc(({
         }, jsdocTag);
       }
     } else if (startsWithHyphen) {
-      report(`There must be no hyphen before @${targetTagName} description.`, (fixer) => {
-        const [
-          unwantedPart,
-        ] = /^\s*-\s*/u.exec(desc);
+      let lines = 0;
+      for (const {
+        tokens,
+      } of jsdocTag.source) {
+        if (tokens.description) {
+          break;
+        }
 
-        const replacement = sourceCode
-          .getText(jsdocNode)
-          .replace(desc, desc.slice(unwantedPart.length));
+        lines++;
+      }
 
-        return fixer.replaceText(jsdocNode, replacement);
-      }, jsdocTag);
+      utils.reportJSDoc(
+        `There must be no 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*-\s*/u, '',
+              );
+              break;
+            }
+          }
+        },
+        true,
+      );
     }
   };
 
diff --git a/test/rules/assertions/requireHyphenBeforeParamDescription.js b/test/rules/assertions/requireHyphenBeforeParamDescription.js
index 16fed038c..34e527d6b 100644
--- a/test/rules/assertions/requireHyphenBeforeParamDescription.js
+++ b/test/rules/assertions/requireHyphenBeforeParamDescription.js
@@ -371,7 +371,82 @@ export default {
           }
       `,
     },
-
+    {
+      code: `
+      /**
+       * Split a unit to metric prefix and basic unit.
+       *
+       * @param {string} unit - Unit to split.
+       * @param {string} [basicUnit] - Basic unit regardless of the metric prefix.
+       *     If omitted, basic unit will be inferred by trying to remove the metric
+       *     prefix in \`unit\`.
+       *
+       * @returns {{ prefix: string, basicUnit: string }} - Split result.
+       *     If \`unit\` does not have a metric prefix, \`''\` is returned for \`prefix\`.
+       *     If \`unit\` does not have a basic unit, \`''\` is returned for \`basicUnit\`.
+       */
+      `,
+      errors: [
+        {
+          line: 10,
+          message: 'There must be no hyphen before @returns description.',
+        },
+      ],
+      options: [
+        'always',
+        {
+          tags: {
+            '*': 'never',
+            property: 'always',
+          },
+        },
+      ],
+      output: `
+      /**
+       * Split a unit to metric prefix and basic unit.
+       *
+       * @param {string} unit - Unit to split.
+       * @param {string} [basicUnit] - Basic unit regardless of the metric prefix.
+       *     If omitted, basic unit will be inferred by trying to remove the metric
+       *     prefix in \`unit\`.
+       *
+       * @returns {{ prefix: string, basicUnit: string }} Split result.
+       *     If \`unit\` does not have a metric prefix, \`''\` is returned for \`prefix\`.
+       *     If \`unit\` does not have a basic unit, \`''\` is returned for \`basicUnit\`.
+       */
+      `,
+    },
+    {
+      code: `
+      /**
+       * @returns {{
+       *   prefix: string, basicUnit: string
+       * }} - Split result.
+       */
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'There must be no hyphen before @returns description.',
+        },
+      ],
+      options: [
+        'always',
+        {
+          tags: {
+            '*': 'never',
+            property: 'always',
+          },
+        },
+      ],
+      output: `
+      /**
+       * @returns {{
+       *   prefix: string, basicUnit: string
+       * }} Split result.
+       */
+      `,
+    },
   ],
   valid: [
     {