Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
jaydenseric opened this issue Sep 20, 2023 · 2 comments
Open

Comments

@jaydenseric
Copy link
Contributor

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
Copy link

Andrioden commented 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

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

Allowed (fixable)

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

@brettz9
Copy link
Collaborator

brettz9 commented 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants