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. + */ + `, + }, ], });