Option for `lines-before-block` to ignore single-line jsdoc comments

[ehoogeveen-medweb]

Motivation

When documenting parameters, simple single-line descriptions can be enough. For example:

/** The parameters for a request */
export type RequestParams = {
    /** The year to retrieve. */
    year: `${number}`;
    /** The month to retrieve. */
    month: `${number}`;
}

In this case, I don't think newlines before the jsdoc comments add any value.

Current behavior

The rule warns even with ignoreSameLine: true, as the jsdoc is on a separate line.

Desired behavior

Don't warn if the jsdoc fits on a single line.

Alternatives considered

• Don't warn if the jsdoc fits on a single line and only contains a description. That would be enough for the example above, but another use case is providing type information for a variable on the next line in javascript, and I don't think requiring a preceding newline helps much there either.

[JoshuaKGoldberg]

IMO this option would be best enabled by default. This succinct / one-line style is pretty common in projects, and it's surprising for many to see the linter report against it.

[thernstig]

Although, if it was a /** @type {string[]} */ e.g. for a top-level variable I would expect it to have a line break before. Tricky.

[ehoogeveen-medweb]

I'm not sure I would want to enforce it:

function foo() {
  /** @type { string[] | undefined } */
  let myStringArray;
  /** @type { number[] | undefined } */
  let myNumberArray;
  // ...
}

(assuming also https://github.com/gajus/eslint-plugin-jsdoc/issues/1296) looks reasonable to me.

[JoshuaKGoldberg]

Checking in, sorry for the ping @gajus. I just want to confirm - would you be open to a PR that makes checking single-line JSDoc comments an opt-in option?

(same question for #1296)

[gajus]

I am not person to ask. @brettz9 has been maintaining this repo the past several years.

[JoshuaKGoldberg]

Ah sorry! Same question on these two issues for @brettz9 then 🙂

[brettz9]

@JoshuaKGoldberg : SGTM!