Feature request: Add support to decorators

[alejandroclaro]

I'm trying to use eslint-plugin-jsdoc in a project where decorators are been used and needed in general. However, the rule 'jsdoc/require-jsdoc' warns about missing documentation when the decorator is placed between the comment and the entity:

/**
 * Class documentation
 */
 @AnyDecorator({
  'property': 'value'
})
export default class Foo {
 // ....
}

The alternative is to move the decorator before the comment. But it does not look good and it's error-prone.

 @AnyDecorator({
  'property': 'value'
})
/**
 * Class documentation
 */
export default class Foo {
 // ....
}

It will be good that this feature is supported, even with decorators in stage 2. It has become a fairly common feature in many libraries lately. It is quite annoying to work with the alternative option in projects where documentation is a mandatory requirement and such a valuable tool as this plugin helps to detect violations.

[brettz9]

If you want to dig into this, you can take a look at https://github.com/brettz9/eslint-plugin-jsdoc/tree/require-jsdoc-decorators . It was trivial to allow a bare @decorator, but with parenthesized tokens prior, it would require some parentheses-and-type matching. If you log tokenBefore, you can introspect on the tokens.

This is not a priority for me to complete this, but it was easy enough to demo the kind of approach that would be needed.

For testing, I recommend running npm run test-index --rule=require-jsdoc --valid=-1. This will let you just run the last "valid" rule in the require-jsdoc test file, and you can do logging to see what is going on.

[brettz9]

I've since merged my branch to handle intervening simple decorators, so that can now be found in master (added with 641479b).

[brettz9]

The decorator in the example has been working now as intended, so closing. Feel free to reopen if we are not properly skipping over some forms of decorators to expect or place the comment block above the decorator.

[boy51]

Hi, I'm still having issues in a NestJS project where decorators are used extensively. I hope this is the right place to post as I'm not sure if it's a bug or an issue in my config.

Overall the rule is working but when it comes to class declarations it doesn't seem to properly skip over decorators.

/**
 * This jsdoc isn't recognized
*/
@Controller('user-settings')
@UseGuards(AuthGuard())
export class UserSettingsController { // <------- This still gives me a require-jsdoc warning
  /**
   * This jsdoc is recognized even with decorators in between.
   * @param {UbwUser} user
   * @return {Promise<UserSettings>}
   */
  @Get()
  async getUserSettings(@GetUser() user: UbwUser): Promise<UserSettings> { // <----- This is ok
    const settings = await this.userSettingsService.getUserSettings(user.id)
    delete settings.userId

    return settings
  }
}

The problem here is that, if the doc is placed above class declaration and below decorators, VSCode doesn't seem to recognize the doc, and if the doc is placed above decorators of class declaration, eslint doesn't recognize it.

I haven't experienced this issue anywhere else. Only with class declarations.

Here's my eslint config. I'm using eslint-config-google on top of eslint-recommended.

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: 'tsconfig.json',
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint/eslint-plugin'],
  extends: [
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
    'google',
    'prettier',
    'prettier/@typescript-eslint',
  ],
  root: true,
  env: {
    node: true,
    jest: true,
  },
  rules: {
    '@typescript-eslint/explicit-function-return-type': 'off',
    '@typescript-eslint/no-explicit-any': 'off',
    'new-cap': 'off',
    'require-jsdoc': [
      'warn',
      {
        require: {
          FunctionDeclaration: true,
          MethodDefinition: true,
          ClassDeclaration: true,
        },
      },
    ],
    semi: ['error', 'never'],
  },
}

[brettz9]

Please file a new issue with the requested info, and indicate the version of eslint-plugin-jsdoc you are using. I'm not seeing an issue against the current version, though I don't know if the tsconfig could have anything to do with it. Please also try to reduce your config to the minimum that finds the problem, and if it needs tsconfig, please supply your tsconfig in the issue. Thanks!