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 foo are 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 foo are 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"].