gajus / eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.
Other
1.09k stars 157 forks source link

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

Open jaydenseric opened 1 year ago

jaydenseric commented 1 year ago

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 commented 1 year ago

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 commented 11 months ago

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