Enforcing single line JSDoc comments if it fits within a line length

[jaydenseric]

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.

[Andrioden]

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

    /**
     * @param {object} data
     */
    static coolMethod(data) {
    }

Allowed (fixable)

    /** @param {object} data */
    static coolMethod(data) {
    }

[brettz9]

A heads up that my energy has not been great, so may not be able to undertake the likes of this issue.

[lkraav]

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]

Don't know why, but I lived under the impresson that /// were JSDoc line comments. Just searching for why VSCode doesn't understand this :D

[brettz9]

@jaydenseric : Finally got around to this. Take a look at #1409 to see if that meets your needs. Also applies @Andrioden 's suggestion.

[Andrioden]

@brettz9 i took a quick look, that looks like what i wanted yes. Added one comment.

[brettz9]

@ackvf : You are probably thinking of https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html . JSDoc requires /** at the beginning.

[brettz9]

@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.