diff --git a/.README/rules/require-hyphen-before-param-description.md b/.README/rules/require-hyphen-before-param-description.md
index bb490f17..9193bba4 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,10 @@ 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, they will actually be forbidden
+in the event that they are at 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 6022aa17..33163088 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,10 @@ 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, they will actually be forbidden
+in the event that they are at 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 +206,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 before @param description.
````
@@ -294,5 +306,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 cc2617d9..8a5749f3 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,26 +43,35 @@ 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(
@@ -76,6 +87,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 1cb254c2..1fe37376 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 before @param description.',
+ },
+ ],
+ 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.
+ */
+ `,
+ },
],
});