feat: add require-asterisk-prefix rule

[skeggse]

This rule checks that each line of the jsdoc comment starts with an asterisk. For composability with
other rules, this does not check the alignment or indentation of the comment content.

• The naming of this rule is entirely provisional - better name suggestions welcome!

Fixes #199

[gajus]

This rule should be require-asterisk-prefix with a toggle "always"/ "never". There are style guides that consider * prefix in comment body redundant.

[skeggse]

The challenge I see with a "never" option is that I'm not sure there's an unambiguous way to lint that mode:

/**
 User encapsulates the data and methods needed to manage user objects.

 **Never instantiate this without a FIPS-compliant crypto module installed!**

 *some italics for good measure*

 @param {string} userId
 */
class User { ... }

Two lines in this jsdoc block in a naive solution would be incorrectly marked as problems due to having a *-prefix. Can you link me to the aforementioned style guides? A more formal definition of the syntax might help disambiguate these cases.

[leomeloxp]

The challenge I see with a "never" option is that I'm not sure there's an unambiguous way to lint that mode:

The way I interpret these options is:

"require-asterisk-prefix": [2, "always"]:

Always require a * as a prefix for JSDocs lines.

"require-asterisk-prefix": [2, "never"]:

Never require a * as a prefix for JSDocs lines. If they exist as something other than a prefix it's okay, and we can't really enforce a style guide for this, ie, you can have multiple adjacent lines beginning with a *.

The only check for never that I would possibly suggest would be to fail the check if ALL lines start with a * and follow the same pattern. Eg:

BAD

/**
 * A comment
 * that follows
 * a pattern
 */ 

GOOD

/**
 * A comment
 *that does
*not follows
 ** a pattern
 */ 

Thanks for putting this PR together. Hope my comment helps.

[skeggse]

How does ["error", "never"] differ from "off", then? Just the check for all lines? Seems like a heuristic that'd be really rarely hit and be a false positive just as often as a true positive.

[leomeloxp]

If you add the check to ensure the * are not making a pattern that's where they'd differ (see GOOD and BAD examples above).

If you don't add that check then it would have no difference at all, which is not great but not necessarily a bad thing either in this case.

[brettz9]

I figure some might also end up asking for an "asterisks multiline everywhere except in certain tags" style as well (e.g., @example or @license).

[brettz9]

Both types should now be easier to support with comment-parser having been updated to allow for precise AST/tokens.

[brettz9]

I think this PR may be ready now.

There can probably be improvements in adding missing asterisks, but it isn't always clear how to do this, e.g., if someone had:

    /**
     *
  Desc.
     */

or

    /**
     *
         Desc.
     */

...we should probably use the asterisks before and after to align them, but the problem is that any or all of them might be out of alignment, even on purpose. Right now, our fixer to add the asterisk just:

1. If there was no text at all previously, set to the indent level
2. Adds a space after the inserted asterisk if there is a tag or description (and sets it to nothing otherwise).

[brettz9]

Two further comments:

1. As mentioned we do little in this PR with asterisks being added in causing alignment questions or issues in the fixer. I think this should actually not be an issue, because there is already the check-alignment rule which can be used to clean that up further if desired.
2. As far as the earlier discussion about what "never" means, since JSDoc does not appear to have specified that lines with tags must begin with an asterisk (they are not necessary in any case with /** @tag */), and since our JSDoc block parser, comment-parser, allows (reasonably I think) for tag lines without asterisks, "never" now truly means do not add them ever (though the tags option can be used to override where they should be required or optionally permitted (via the new "any" option)). If you want to enforce special alignment, that can be handled by check-alignment or a new option thereto (though I don't see a use case for requiring that asterisks be misaligned).

[gajus]

🎉 This PR is included in version 33.2.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀