jsdoc/no-bad-blocks vs ESLint default multiline-comment-style

[thernstig]

I think this a docs issue, but am unsure.

https://eslint.org/docs/rules/multiline-comment-style exists with the option

separate-lines: Disallows block comments in favor of consecutive line comments

jsdoc/no-bad-blocks exists with the option:

preventAllMultiAsteriskBlocks: A boolean (defaulting to false) which if true will prevent all multi-asterisked blocks even those without apparent tag content.

I am merely wondering if these two cover the exact same scenario, and preventAllMultiAsteriskBlocks preventAllMultiAsteriskBlocks could be removed completely in favor of the default in ESLint?

[brettz9]

It looks like the separate-lines option will trigger for all block comments (even JSDoc ones).

Its bare-block option is about preventing * on individual lines (and preventing all line comments).

preventAllMultiAsteriskBlocks, on the other hand, fires only for the likes of /***. By "multi-asterisked blocks", we are referring to the asterisks that make something confuseable with JSDoc--nothing to do with asterisks later in the block. I've added some clarifying text.

[gajus]

🎉 This issue has been resolved in version 37.5.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[thernstig]

@brettz9 Thanks for the update.

It looks like the separate-lines option will trigger for all block comments (even JSDoc ones).

Is this true? We have set:

"multiline-comment-style": ["error", "separate-lines"],
"jsdoc/no-bad-blocks": ["warn", { "preventAllMultiAsteriskBlocks": true }]

But it does not trigger on JSDoc block comments. I.e. for normal comments (non JSDoc) we want only this allowed, which works with the above settings:

// comment
// comment continue
// comment continue

It seems in my scenario then I will not need to set preventAllMultiAsteriskBlocks: true as "multiline-comment-style": ["error", "separate-lines"] should be sufficient.

[brettz9]

@brettz9 Thanks for the update.

It looks like the separate-lines option will trigger for all block comments (even JSDoc ones).

Is this true? We have set:

I hadn't confirmed it, no. I just assumed that as the docs made no mention of an exception for JSDoc, and the examples showed problematic code including block comments, that it would not be different. But in looking at the source code for the ESLint test cases for this rule, I do see that JSDoc blocks are considered as valid with this option.

Also note though that so are:

/* eslint semi: "error" */

and

/* eslint semi: [
    "error"
] */

and

/* this is
                   a comment */ foo;

Our option is concerned with, and only concerned with 3 asterisks or more

"multiline-comment-style": ["error", "separate-lines"],
"jsdoc/no-bad-blocks": ["warn", { "preventAllMultiAsteriskBlocks": true }]

But it does not trigger on JSDoc block comments. I.e. for normal comments (non JSDoc) we want only this allowed, which works with the above settings:

// comment
// comment continue
// comment continue

It seems in my scenario then I will not need to set preventAllMultiAsteriskBlocks: true as "multiline-comment-style": ["error", "separate-lines"] should be sufficient.

Perhaps not, though their code might allow:

/*** something on a single line */

or

/*** something on two lines
   leading into a single line */ someCode;

...which ours would not.

[thernstig]

Agree, I also figured that out after I wrote my issues and have kept { "preventAllMultiAsteriskBlocks": true }. Thanks!

The ESLint docs should probably be more specific there mentioning that JSDoc block comments are still allowed.

[brettz9]

Agree, I also figured that out after I wrote my issues and have kept { "preventAllMultiAsteriskBlocks": true }. Thanks!

The ESLint docs should probably be more specific there mentioning that JSDoc block comments are still allowed.

Ugh, I was mistaken here too. They do make mention of it, but just not where the examples are:

The rule always ignores directive comments such as /* eslint-disable */. Additionally, unless the mode is "starred-block", the rule ignores JSDoc comments.