check-line-alignment with "always" breaks with @param, @return, and no types

[TGCrystal]

This issue is very similar to #891, except it applies when both the param and return (or returns) tags are present. Rather than aligning the return description with the param description, extra whitespace before the return description is added.

Expected behavior

No errors are given.

Actual behavior

The following error is given for either test case below:

Expected JSDoc block lines to be aligned  jsdoc/check-line-alignment

ESLint Config

{
    "plugins": [
        "jsdoc"
    ],
    "rules": {
        "jsdoc/check-line-alignment": [
            2,
            "always"
        ]
    }
}

ESLint sample

/**
 * Function description.
 *
 * @param lorem Description.
 * @param sit   Description multi words.
 * @returns     Return description.
 */
const fn = ( lorem, sit ) => {};

and

/**
 * Function description.
 *
 * @param lorem Description.
 * @param sit   Description multi words.
 * @return      Return description.
 */
const fn = ( lorem, sit ) => {};

Environment

• Node version: 16.13.2
• ESLint version 8.17.0
• eslint-plugin-jsdoc version: 39.3.3

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[brettz9]

Hmm. I see that the current behavior is to recommend:

      /**
       * Function description.
       *
       * @param    lorem Description.
       * @param    sit   Description multi words.
       * @returns        Return description.
       */
      const fn = ( lorem, sit ) => {};

There is at least one extra space after the tag names for sure (as the default is to have just one sapace). But I can see why a project might want the names in its own column.

@renatho : Do you have thoughts about the intended result for this? The WordPress standard you pointed to, in their extended example (one has to click to expand it), under https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/#functions , does not seem to even push the @return description past the @param names to align with the @param description, so I'm not sure that we want to be pinning to this standard (or, if we are, we are far from it given that that spec states "Related comments should be spaced so that they align to make them more easily readable.").

@TGCrystal is requesting a behavior still different from your approach or the WordPress spec, in aligning across different tag groups, but not apparently wishing to add space for a name column when no name is present. I'm not sure such a suggestion fits with the rule given it differs both from current behavior and the WordPress spec, but it'd be nice if you could respond to it.

Unless we are perfectly following that spec, I think we should be specifying more clearly what we are doing. Btw, note that I also made another fix recently in 26e7357 though that was I think more clear-cut.

[TGCrystal]

For some reason, I don't seem to be getting that as the currently recommended fix. Instead, I am getting

      /**
       * Function description.
       *
       * @param lorem Description.
       * @param sit   Description multi words.
       * @returns       Return description.
       */
      const fn = ( lorem, sit ) => {};

[renatho]

@renatho : Do you have thoughts about the intended result for this? The WordPress standard you pointed to, in their extended example (one has to click to expand it), under https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/#functions , does not seem to even push the @return description past the @param names to align with the @param description, so I'm not sure that we want to be pinning to this standard (or, if we are, we are far from it given that that spec states "Related comments should be spaced so that they align to make them more easily readable.").

Hey folks! 👋 Sorry for the delay to answer it!

For WP, I raised the PR to check it only for some tags. See it here: https://github.com/WordPress/gutenberg/blob/v13.6.0-rc.1/packages/eslint-plugin/configs/jsdoc.js#L119. In Sensei LMS we're also using that and using a similar plugin for prettier, if someone is interested in: https://github.com/Automattic/sensei/blob/version/4.5.1/scripts/prettier/prettier-plugin-jsdoc.js. It also uses the @es-joy/jsdoccomment.

But it would be an amazing feature if we could align it based on "groups" (maybe it could be based on break lines). Currently, I think it's intended to align all the tags that are set (or the default ones).

[MorevM]

I experienced this as well.

If both @param and @returns have no types, then the descriptions are misaligned