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

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

Closed
TGCrystal opened this issue Jun 18, 2022 · 4 comments · Fixed by #909
Closed

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

TGCrystal opened this issue Jun 18, 2022 · 4 comments · Fixed by #909

Comments

@TGCrystal
Copy link
Contributor

TGCrystal commented Jun 18, 2022

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

brettz9 commented Jun 18, 2022

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

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

renatho commented Jun 29, 2022

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

MorevM commented Jul 30, 2022

I experienced this as well.

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

Temp - Figma_220730135058

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