Feature request: rule to enforce asterisks

[c-vetter]

It would be nice to have a rule that enforces every line in a JSdoc comment to start with an asterisk, as in https://palantir.github.io/tslint/rules/jsdoc-format/

[golopot]

Comparison between tslint/jsdoc-format and eslint-plugin-jsdoc:

• each line contains an asterisk - jsdoc/require-asterisk-prefix (Brett editing post to check off)
• asterisks must be aligned - jsdoc/check-alignment
• disallow extra space after asterisks - jsdoc/check-indentation
• require newline after main description - jsdoc/newline-after-description
• require one space after asterisks - jsdoc/check-line-alignment
• bare block comment: disallow asterisks (Is this a reference to "one line comments must start with /** and end with */"?); if so, I think this could be merged with item below not to allow any multiple asterisks (Brett editing post to add)
• multiline comments don’t allow text after /** in the first line (under option) Multiline blocks #733
• [ ] the only characters before the asterisk on each line must be whitespace characters - seems it would be hard to distinguish from asterisks intended within descriptions (Brett editing post to add)

Both unsupported:

• disallow asterisks - jsdoc/require-asterisk-prefix (Brett editing post to add and check off)
• disallow extra spaces in between tag name, types, and names - jsdoc/check-line-alignment (Brett editing post to check off)
• disallow (or require) lines between tag blocks (Add rule to (dis)allow empty lines between tags #93 / feat: new rule tag-line; fixes #93 #727)
• Avoiding multiple asterisks (beyond the obligatory first two), whether at the beginning (no-bad-blocks: add preventAllMultiasteriskBlocks option #728), end, or middle (when preceded only by whitespace and not followed by whitespace) (Brett editing post to add) no-multi-asterisks rule #730
• Avoiding single line jsdoc blocks such as /** @param abc */, perhaps excepting some tags like @lends which, um, "lend" themselves to single line expressions because of their terseness. Could conversely, as requested in Feature Request: Require single line JSDoc for short comments #724 , require single line comments at least when under a certain length and/or if tags or particular tags were present (Brett editing post to add) Multiline blocks #733

[skeggse]

I submitted a PR for this at #446. Not amazingly happy about the name, though - thoughts?

[brettz9]

Other checks I can think of on this general topic might be:

1. Avoiding multiple asterisks (beyond the obligatory first two), whether at the beginning, end, or middle
2. Avoiding single line jsdoc blocks such as /** @param abc */, perhaps excepting some tags like @lends which, um, "lend" themselves to single line expressions because of their terseness.

[gajus]

🎉 This issue has been resolved in version 33.2.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[brettz9]

I've turned @golopot 's comment into a kind of wiki-style comment, adding my own items (though marked as being added by me), so we could track the items for this issue all in one place. The require/forbid asterisk rule has been added/released, but not these other items.

[brettz9]

Regarding reporting jsdoc blocks with multiple asterisks at the beginning, I've just pushed a fix at 28397c7 so that no-bad-blocks can also check 3+ asterisks when what appears to be a tag is found therein. That case is being handled separately because multiple asterisks at the beginning are not actually jsdoc (so we use that rule to catch comments which look like jsdoc).

I've also filed #728 so as to allow preventing /*** ... */ in that rule even where the contents appear to have no tag (normally not prevented since it could just be a multiline comment with a lot of asterisks).

[brettz9]

After the current PRs, I think the one remaining item here would belong in a rule like multiline-comments with options;

1. No line 0 text if multiline
2. Avoid single line entirely, unless optionally possessing specific tags like @lends
3. Require single lines only, optionally if under a certain length and/or if tags and/or particular tags are present

[brettz9]

After the current PRs, I think the one remaining item here would belong in a rule like multiline-comments with options;

1. No line 0 text if multiline

2. Avoid single line entirely, unless optionally possessing specific tags like `@lends`

3. Require single lines only, optionally if under a certain length and/or if tags and/or particular tags are present

Btw, @golopot , it'd be great to have your feedback in before I prepare the PRs. Thanks...

[gajus]

🎉 This issue has been resolved in version 34.6.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[danvk]

I'm not sure whether tslint enforced this, but another asterisk-related formatting issue I sometimes see is not putting the trailing */ on its own line in a multiline block.

For example, rather than writing it like this:

/**
 * This is a multline
 * jsdoc comment */

the more canonical way to write it is like this:

/**
 * This is a multline
 * jsdoc comment
 */

It looks like no-multi-asterisks is in the ballpark, but doesn't quite enforce this.

[brettz9]

Please file as a new issue. Thanks!

[brettz9]

And, btw, I think it would be fine as a new option under multiline-blocks given the rule's already handling single line blocks).

[danvk]

@brettz9 sure, filed #738