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

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.

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) {
    }

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

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.

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

fix(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…

feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…

@jaydenseric

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

feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…

@brettz9

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

@ackvf

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

@lkraav

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

feat(`multiline-blocks`): adds `requireSingleLineUnderCount` option; f…

🎉 This issue has been resolved in version 51.3.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

@brettz9

@brettz9 - Works almost perfectly. Thou there is a minor bug with multi-line types, but i found a workaround.

eslint.config.js

            "jsdoc/multiline-blocks": ["error", {
                requireSingleLineUnderCount: 120
            }],

raises error 11:5 error Description is too short to be multi-line jsdoc/multiline-blocks

export class BattleDialog {
    /**
     * @type {{
        visible: import("vue").Ref<boolean>,
        attack: import("vue").Ref<AttackPve|AttackPvp|undefined>,
        hero: import("vue").Ref<HeroOwn|undefined>,
        outpost: import("vue").Ref<Outpost|undefined>,
        rewards: import("vue").Ref<Rewards|undefined>
     * }}
     */
    static viewing = {
        visible: ref(false),
        attack: ref(undefined),
        hero: ref(undefined),
        outpost: ref(undefined),
        rewards: ref(undefined)
    }
}

workaround with dot in description

export class BattleDialog {
    /**
     * . <------- Had to add a dot
     * @type {{
        visible: import("vue").Ref<boolean>,
        attack: import("vue").Ref<AttackPve|AttackPvp|undefined>,
        hero: import("vue").Ref<HeroOwn|undefined>,
        outpost: import("vue").Ref<Outpost|undefined>,
        rewards: import("vue").Ref<Rewards|undefined>
     * }}
     */
    static viewing = {
        visible: ref(false),
        attack: ref(undefined),
        hero: ref(undefined),
        outpost: ref(undefined),
        rewards: ref(undefined)
    }
}

@Andrioden

@Andrioden : Thanks for the report. I've fixed this for multi-line types in #1422 (v51.3.2).

Navigation Menu

Repository navigation

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

Motivation

Current behavior

Desired behavior

Alternatives considered

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Motivation

Current behavior

Desired behavior

Alternatives considered

Activity

Andrioden commented on Sep 23, 2023

brettz9 commented on Oct 16, 2023

lkraav commented on May 20, 2025

ackvf commented on Jun 16, 2025

brettz9 commented on Jun 21, 2025

Andrioden commented on Jun 21, 2025

brettz9 commented on Jun 21, 2025

brettz9 commented on Jun 21, 2025

github-actions commented on Jun 30, 2025

Andrioden commented on Jul 1, 2025

brettz9 commented on Jul 2, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions