Plugin shows TypeScript param types missing

[rlnt]

Expected behavior

The plugin shouldn't show missing param and return types for a function in TypeScript.
Param and return types are usually inferred from the function itself when IntelliSense is
provided and I often read that it could cause issues if you redefine them again in the JSDoc.

Actual behavior

It shows that there are missing param and return types for a function

ESLint Config

{
  "env": {
    "commonjs": true,
    "es6": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:jsdoc/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2018,
    "sourceType": "module"
  },
  "plugins": ["@typescript-eslint"],
  "rules": {
    "prefer-const": "warn",
    "no-empty-function": "warn",
    "no-unused-vars": "off"
  }
}

ESLint sample

/**
 * Returns true if the backend is successfully connected.
 *
 * @returns True if the backend is online
 */
function getIsOnline(): boolean {
    return isOnline;
}

Results in:

Missing JSDoc @returns type.

Environment

• Node version: v15.4.0
• ESLint version v7.16.0
• eslint-plugin-jsdoc version: v30.7.9

[rlnt]

If you think this is the expected behavior and TypeScript doesn't have a problem with types being re-set in the function documentation, let me know.

[brettz9]

You can add the no-types rule to disallow type usage on param and returns (or their aliases).

TypeScript documents examples with the types: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param , so I'm not sure whether we want to add the no-types rule by default (and it would require a new TypeScript-specific config).

[brettz9]

Oh, and disable require-param-type, so, add the likes of:

"rules": {
    "jsdoc/no-types": "warn",
    "jsdoc/require-param-type": "off"
}

[rlnt]

I know there are rules to disable this behavior. I just thought it should be default but you are right. It is shown like that in the example on the TypeScript documentation. I will report back if this causes any issues in the future.

Thanks for the clarification! :)

[rlnt]

@brettz9 just to add something to this conversation.
I opened this issue because of this extension: https://marketplace.visualstudio.com/items?itemName=salbert.comment-ts

Where it says "avoids warnings like" and then it says annotations are redundant and should be removed.

[brettz9]

Sure. It makes sense, but it does seem that that comes from a third party repo: https://github.com/s-albert/comment-ts , and as much as enforcing the rule makes sense, I'd hesitate to impose this by default on projects when TS itself doesn't. You might see if Microsoft would want to enforce such a rule.

[rlnt]

Yeah, I assumed that you see it like that. I just wanted to give a source where I read that. I was searching for it because I couldn't remember where this was mentioned.

All good. I like the type annotations. They are way more clean imo.