Remove leading empty lines in descriptions.

[jespertheend]

Motivation

VSCode automatically adds an empty line at the start of JSDoc comments, but I don't necessarily always want to add a description, so sometimes I end up with comments like these:

/**
 *
 * @param {number} x
 */
function functionWithClearName(x) {}

Current behavior

No errors.

Desired behavior

An error with autofix that removes the empty line:

/**
 * @param {number} x
 */
function functionWithClearName(x) {}

Alternatives considered

I'm using match-description for now:

"jsdoc/match-description": ["error", {
	matchDescription:"^\\S",
	message: "JSDoc comments may not start with an emtpy line.",
}],

[brettz9]

What do you want to happen to:

/**
 *
 */

And under what circumstances does VS Code add an extra line? I think our jsdoc/require-param may do so when params are missing; is this the circumstance or can you reproduce under other conditions?

[jespertheend]

Completely empty comments can be left as is for me personally, I've never run across that situation yet.

I don't have jsdoc/require-param enabled so that's not the case for me.
VSCode adds the empty line when you type /** and hit enter above a function like so:

Screen.Recording.2023-02-05.at.01.17.05.mp4.mp4

You can use tab to jump to the next section, which gives you a chance to delete the extra line in case you don't want a description.

But I often run across the situation where two parameters have the same type:

Screen.Recording.2023-02-05.at.01.18.45.mp4.mp4

In that case I use ⌘⌥⇧↓ to select the second type, but once you've done that tab no longer jumps to the empty line so I often forget to remove it.

[brettz9]

I'm guessing you must have some other extension installed or something because typing /** and hitting enter above a function with a parameter does not add the parameter for me in VSC.

[jespertheend]

I'm trying it on https://vscode.dev/ in an incognito window, and while I am able to get it to work without changing any settings, it seems rather unpredictable. I think it needs to load TypeScript first or something. But once it works it keeps working even after refreshing.

I also can't get it to work without saving a file to disk and then opening it. And it seems to need at least some references to types for it to start downloading TypeScript. I'm using a file with the following contents:

/**
 * @param {number} x
 * @param {number} y
 */
function foo(x,y) {

}

function bar(x, y) {

}

[github-actions]

🎉 This issue has been resolved in version 40.3.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[thernstig]

@brettz9 did you miss to add this to the table in https://github.com/gajus/eslint-plugin-jsdoc#configuration?

[brettz9]

@thernstig : Thanks, added in #1016

[thernstig]

@brettz9 how about auto-generating the table from https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/index.js? :)