[require-hyphen-before-param-description]: Except when line break #1435
Description
Motivation
I want this rule to have an additional argument value, (like "except-line-break"?).
If the description is besides the param name, a hyphen should be added;
if the description is wrapped before the line, no hyphen should be added (except a special case).
Current behavior
When set "jsdoc/require-hyphen-before-param-description": ["error", "always"] currently, it will always add hyphen before the description, even if a line break before it. For example, this will be reported:
@param foo
The possible values for `foo` are as follows.
- `"option1"`: Description of option 1.
- `"option2"`: Description of option 2.The auto fix is as follows:
@param foo
- The possible values for `foo` are as follows.
- `"option1"`: Description of option 1.
- `"option2"`: Description of option 2.This breaks the semantics, it place the description of foo at the same list level as the descriptions of its values.
The manual fix is as follows:
@param foo -
The possible values for `foo` are as follows.
- `"option1"`: Description of option 1.
- `"option2"`: Description of option 2.This is too ugly. And the VSCode parser will have a bug at this time. When you hover the mouse over the variable foo, the description displayed is as follows:
The possible values for
fooare as follows.
"option1": Description of option 1."option2": Description of option 2.
If don't line break before the description, for example:
@param foo - The possible values for `foo` are as follows.
- `"option1"`: Description of option 1.
- `"option2"`: Description of option 2.It will still be rendered as follows, which breaks the semantics.
- The possible values for
fooare as follows."option1": Description of option 1."option2": Description of option 2.
Desired behavior
The following patterns are considered problems:
/**
* @param foo Description of `foo`.
*/
/**
* @param foo -
* The possible values for `foo` are as follows.
* - `"option1"`: Description of option 1.
* - `"option2"`: Description of option 2.
*/the following patterns are not considered problems:
/**
* @param foo - Description of `foo`.
*/
/**
* @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.
*/Note that in this special case, this pattern is not considered problems, because the leading hyphen is part of an unordered list.
/**
* @param foo
* - `"option1"`: Description of option 1.
* - `"option2"`: Description of option 2.
*/Alternatives considered
Additional info
On an unrelated note, I suggest changing the default value of the tags attribute of require-hyphen-before-param-description rule from ["param"] to ["param", "template", "property"].