Option to support or ban hyphens before other tag descriptions

[0xCLARITY]

Motivation

We use the require-hyphen-before-param-description rule, and in some cases, people get confused and add hyphens for other JSDoc tags. The most common one I see is adding a hyphen to the @returns tag.

Current behavior

No way to discourage writing something like:

/**
 * ...
 * @returns - description
 */

Desired behavior

Have some way to discourage using hyphens for JSDoc tags that are not @param.

Alternatives considered

I tried using the match-description and setting a regex, but it seemed to ignore the presence/absence of a hyphen.

[brettz9]

Since require-hyphen-before-param-description already has the logic and despite its name can check @property too, how about we add an array option (e.g., tags) to it whose items would be objects with keys such as perhaps tagName and circumstance: "always|never". We could potentially allow any as well so that the main options would apply to all tags.

[0xCLARITY]

That sounds reasonable to me!

[0xCLARITY]

@brettz9 , are there any rules you can point me to as an example that have an array of tag objects with a circumstance property?

I took a quick look at the require-hyphen-before-param-description source, but it's non-obvious to me how to refactor this to loop through an array of tags that may or may not have circumstance === always

[brettz9]

I've submitted PR #555 which simplifies from my proposal to use an array of tagName + circumstance objects to instead just use a single tags object with tag names as keys and circumstances as values.

[brettz9]

And * as a key for the "any" situation.

[0xCLARITY]

#555 looks great! Thanks for implementing this!

[gajus]

🎉 This issue has been resolved in version 27.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀