diff --git a/.README/rules/require-hyphen-before-param-description.md b/.README/rules/require-hyphen-before-param-description.md
index bb490f176..87403b0db 100644
--- a/.README/rules/require-hyphen-before-param-description.md
+++ b/.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):
diff --git a/docs/rules/require-hyphen-before-param-description.md b/docs/rules/require-hyphen-before-param-description.md
index 6022aa17c..0fa4f882d 100644
--- a/docs/rules/require-hyphen-before-param-description.md
+++ b/docs/rules/require-hyphen-before-param-description.md
@@ -15,7 +15,7 @@ Requires (or disallows) a hyphen before the `@param` description.
## Fixer
-(Todo)
+Adds a hyphen for "always" and removes a hyphen for "never".
@@ -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.
+ */
````
diff --git a/src/rules/requireHyphenBeforeParamDescription.js b/src/rules/requireHyphenBeforeParamDescription.js
index cc2617d94..d48b4e32b 100644
--- a/src/rules/requireHyphenBeforeParamDescription.js
+++ b/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;
}
}
diff --git a/test/rules/assertions/requireHyphenBeforeParamDescription.js b/test/rules/assertions/requireHyphenBeforeParamDescription.js
index 1cb254c25..be5b4beee 100644
--- a/test/rules/assertions/requireHyphenBeforeParamDescription.js
+++ b/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.
+ */
+ `,
+ },
],
});