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

jsdoc/require-hyphen-before-param-description not fixing all auto-fixable problems #1074

Closed
thernstig opened this issue May 10, 2023 · 7 comments · Fixed by #1075
Closed

Comments

@thernstig
Copy link

Expected behavior

I expect jsdoc/require-hyphen-before-param-description to auto-fix all problems.

Actual behavior

It does not remove the hyphen before returns in all scenarios. See example below.

ESLint Config

{
  "root": true,
  "reportUnusedDisableDirectives": true,
  "parserOptions": {
    "ecmaVersion": 2023,
    "sourceType": "module"
  },
  "env": {
    "node": true,
    "es2022": true,
  },
  "extends": [
    "plugin:jsdoc/recommended-error"
  ],
  "rules": {
    "jsdoc/require-jsdoc": "off",
    "jsdoc/require-description": "error",
    "jsdoc/check-syntax": "error",
    "jsdoc/check-line-alignment": ["error", "never", { "wrapIndent": "    " }],
    "jsdoc/require-hyphen-before-param-description": [
      "error",
      "always",
      {
        "tags": {
          "*": "never",
          "property": "always"
        }
      }
    ],
    "jsdoc/require-asterisk-prefix": "error",
    "jsdoc/sort-tags": [
      "error",
      {
        "tagSequence": [
          {
            "tags": [
              "since",
              "deprecated",
              "access",
              "public",
              "protected",
              "private"
            ]
          },
          { "tags": ["class", "augments", "mixes"] },
          { "tags": ["alias", "memberof"] },
          { "tags": ["see", "link", "global"] },
          { "tags": ["-other"] },
          { "tags": ["listens"] },
          { "tags": ["param"] },
          { "tags": ["throws"] },
          { "tags": ["fires"] },
          { "tags": ["yields"] },
          { "tags": ["returns"] },
          { "tags": ["example"] }
        ]
      }
    ],
    "jsdoc/tag-lines": ["error", "any", { "startLines": 1 }],
    "jsdoc/no-bad-blocks": ["error", { "preventAllMultiAsteriskBlocks": true }],
    "jsdoc/no-blank-blocks": ["error", { "enableFixer": true }]
  }
}

ESLint sample

/**
 * Split a unit to metric prefix and basic unit.
 *
 * @param {string} unit - Unit to split.
 * @param {string} [basicUnit] - Basic unit regardless of the metric prefix.
 *     If omitted, basic unit will be inferred by trying to remove the metric
 *     prefix in `unit`.
 *
 * @returns {{ prefix: string, basicUnit: string }} - Split result.
 *     If `unit` does not have a metric prefix, `''` is returned for `prefix`.
 *     If `unit` does not have a basic unit, `''` is returned for `basicUnit`.
 */

Environment

  • Node version: v18.14.2
  • ESLint version v8.31.0
  • eslint-plugin-jsdoc version: 44.0.2
@thernstig
Copy link
Author

thernstig commented May 10, 2023

I even noticed something even stranger now. It cannot fix the @param below. It does not add a hyphen, which I expect.

/**
 * Update a foo
 *
 * @public
 *
 * @param {Test} test The test
 *
 * @returns {Promise<Test>} - The test
 */

It does work/fix a lot of problems, but also does not work/fix some problems even though they to me all look the same. I cannot find a pattern.

@brettz9
Copy link
Collaborator

brettz9 commented May 10, 2023

I even noticed something even stranger now. It cannot fix the @param

You have always set for the string setting. This is what is applied to @param.

@brettz9
Copy link
Collaborator

brettz9 commented May 10, 2023

As far as the @returns, what appears to be going on here is that the fixer looks through the description for hyphens to remove and finds them in the param and removes them instead (but they are added back). It instead seems to try a replacement on the description with asterisks vs. without them, and thus fails.. This rule's fixer predates our ability to use parsing to more precisely find the relevant text and replace it.

@github-actions
Copy link

🎉 This issue has been resolved in version 44.2.2 🎉

The release is available on:

Your semantic-release bot 📦🚀

@thernstig
Copy link
Author

thernstig commented May 11, 2023

I even noticed something even stranger now. It cannot fix the @param

You have always set for the string setting. This is what is applied to @param.

always is supposed to add a hyphen, right? The code I showcased above was not --fixed to add a hyhpen.

@brettz9
Copy link
Collaborator

brettz9 commented May 11, 2023

Ok, I see, but have you tested again against the latest version? Seems to be working to add the hyphen for the param if the @returns one is taken care of as it should

@thernstig
Copy link
Author

Tested with the latest release, and it seemed to solve all problems. Even the strange one with @param. I will open a new case if I find more issues.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
@brettz9 @thernstig and others