Enforcing single line JSDoc comments if it fits within a line length #1158
Description
It would be great to have a way of enforcing single line JSDoc comments, if the description is a single line, there are no non-inline JSDoc tags, and the last */ characters would fit within a (configurable?) line length of 80 characters, taking into account the current indentation of the comment.
These would be errors:
/**
* Description.
*/
const foo = true;/**
* Description {@linkcode Foo}.
*/
const foo = true;These would not be errors:
/**
* Description.
* @see https://example.example
*/
const foo = true;/**
* Multiline description:
*
* - Bullet A.
* - Bullet B.
*/
const foo = true;/**
* [A super long single line description](https://example.example/asdf/asdf/as).
*/
const foo = true;const foo = {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
a: {
/**
* Some description that is this long.
*/
a: {},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
},
};Motivation
I regularly review PR's that have many multiline JSDoc comments containing only tiny single line descriptions. They are very verbose and vertically space inefficient; I would like an automated way to ensure such modules have more compact single line JSDoc comments resulting in a smaller module line count.
Current behavior
At first I hoped this would get the desired result:
{
"jsdoc/multiline-blocks": [
"error",
{
noMultilineBlocks: true,
minimumLengthForMultiline: 80,
},
],
}But it seems that minimumLengthForMultiline just counts the length of the description, and doesn't account for the indentation of the comment, etc.
Desired behavior
I would like a new jsdoc/multiline-blocks config option, to enforce the behavior explained above.
Alternatives considered
N/A.
Metadata
Metadata
Assignees
Projects
Milestone
Relationships
Development
Participants
Activity
Andrioden commentedon Sep 23, 2023
I was to about to create a new related issue, but ill jump onto this instead. I would love a similar rule that is fixable. The rule should one-line the jsdoc if the compacted oneliner is below a given rule treshhold line length, the default could be 80 or 120. My motivation is less boilerplated code lines.
Not allowed
Allowed (fixable)
brettz9 commentedon Oct 16, 2023
A heads up that my energy has not been great, so may not be able to undertake the likes of this issue.
lkraav commentedon May 20, 2025
2 years later, I think in a similar vibe I'm trying to auto-fix all single-line JSDoc comments into regular line comments.
But it turns out there is no such rule or a separate plugin. I've spent about an hour digging and hitting dead ends all across.
Line comments
//make more sense because you don't have to manage the trailing closer.ackvf commentedon Jun 16, 2025
Don't know why, but I lived under the impresson that
///were JSDoc line comments. Just searching for why VSCode doesn't understand this :Dfix(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…
feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…
multiline-blocks): addsrequireSingleLineUnderCountoption #1409feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…
brettz9 commentedon Jun 21, 2025
@jaydenseric : Finally got around to this. Take a look at #1409 to see if that meets your needs. Also applies @Andrioden 's suggestion.
feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…
Andrioden commentedon Jun 21, 2025
@brettz9 i took a quick look, that looks like what i wanted yes. Added one comment.
brettz9 commentedon Jun 21, 2025
@ackvf : You are probably thinking of https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html . JSDoc requires
/**at the beginning.brettz9 commentedon Jun 21, 2025
@lkraav : If you want to propose the option names and circumstances, we should be able to convert to single line comments fairly easily. Note that there is the possibility of changing all single-line comments, or changing all single-line comments past a certain length.
feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…
9 remaining items