require-jsdoc rule should ignore annotations in TypeScript files

[saulotoledo]

After TSLint deprecation note, this is the recommended ESLint plugin to be used for documentation. It is also common to use annotations in TypeScript. However, the require-jsdoc rule does not accept the following example:

/**
 * Basic application controller.
 */
@Controller()
export class AppController {
  /**
   * Returns the application information.
   *
   * @returns ...
   */
  @Get('/info')
  public getInfo(): string {
    return 'OK';
  }
}

Expected behavior

The example below should be accepted as valid.

Actual behavior

ESLint will fail with the error "Missing JSDoc comment" until you move the annotations.

ESLint Config

{
  "env": {
    "browser": true,
    "es6": true,
    "node": true
  },
  "extends": [],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "tsconfig.json",
    "ecmaVersion": 6,
    "sourceType": "module"
  },
  "plugins": [
    "jsdoc"
  ],
  "rules": {
    "jsdoc/require-jsdoc": [
      "error",
      {
        "require": {
          "ArrowFunctionExpression": true,
          "ClassDeclaration": true,
          "ClassExpression": true,
          "FunctionDeclaration": true,
          "FunctionExpression": false,
          "MethodDefinition": true
        }
      }
    ]
  }
}

Environment

• Node version: 12
• ESLint version v7.1.0
• eslint-plugin-jsdoc version: 25.4.2

[gajus]

🎉 This issue has been resolved in version 26.0.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[brettz9]

Besides ESLint being independent from TSLint (though thankfully they were on board for TypeScript supporting changes), and despite ESLint recommending this plugin after deprecating (most of) its jsdoc support, eslint-plugin-jsdoc is an independent project from both of them.

However, we have in fact been adding support progressively for TypeScript, so feel free to file such cases of missing support in the future, and perhaps someone may implement. But I mention we are independent as we are not associated with those other projects as part of one official team necessarily committed or obligated to supporting everything TypeScript.

In any case though, this issue has been fixed. Thanks for the report!

[saulotoledo]

@brettz9, thanks for the fix, it will help me a lot!
I upgraded it in my project but I am still seeing the error if I export the class directly. e.g.:

/**
 * This will fail because of 'export'.
 */
@Entity()
export class User { }

/**
 * This will work because there is no export.
 */
@Entity()
class User { }

/**
 * This is also ok.
 */
export class User { }

Could that be added as part of the fix?

[brettz9]

With or without export, and using your options, I am not seeing problems with the latest release. Are you linting from an IDE? If so, have you restarted the IDE after the update?

[saulotoledo]

Hi @brettz9, I am still having the error. I created this to replicate the error (it takes a few seconds to run, but you can see the console output): https://repl.it/@saulotoledo/eslint-jsdoc-requiredoc-issue

Am I doing anything wrong there?

[gajus]

🎉 This issue has been resolved in version 26.0.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[brettz9]

No, your example in that repo was indeed not being recognized. (You have arguments within the decorator in that repo example while such an example was not given here, so, with my not being well familiar with TS/decorators, I had not tested that case.)

This should now be addressed in v26.0.2.

[saulotoledo]

Thanks @brettz9, it worked! :D

[seanblonien]

Using @saulotoledo's https://repl.it/@saulotoledo/eslint-jsdoc-requiredoc-issue example, I found the fixer (eslint --fix) placed the jsdoc comments in between the declaration/definition and decorator instead of strictly above after removing the class' jsdoc.

Could the default behavior place the auto-generated jsdoc above any decorators (including multiline decorators which is actually common in Angular Modules for example)?

[brettz9]

@seanblonien : Sounds reasonable--can you open a new issue though please?