如何用JSDoc 3与Babel.js使用装饰器？字段装饰器报错及配置

Hey there! Let's break down your three questions and solve each one step by step.

1. Fixing the "Stage 2 decorators may only be used with a class or a class method" Error #

This error pops up because you're using the older Stage 2 decorator specification, which only allows decorators on classes themselves, methods, or accessors—not class fields. To fix this, you need to switch to the modern, standard-compliant decorator spec that supports field decorators.

Babel Configuration Steps #

First, install the required plugins:

npm install @babel/plugin-proposal-decorators @babel/plugin-proposal-class-properties --save-dev

Then update your Babel config file (.babelrc or babel.config.json) to enable standard decorator mode:

{
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "legacy": false }],
    ["@babel/plugin-proposal-class-properties", { "loose": false }]
  ]
}

Important: Set loose to false for the class properties plugin—this ensures full compatibility with the standard decorator spec.

2. Can You Add Comments to Decorated Fields? #

Absolutely! Your existing JSDoc comment syntax is totally valid. The error you saw had nothing to do with the comment itself—it was purely a decorator spec mismatch. Once you fix the Babel configuration, your comment will work as expected, whether you're using it for documentation generation, IDE code hints, or type checking.

You can even enhance it with type annotations for better JSDoc support:

class Point {
  constructor(x, y) {
    // ...
  }

  /**
   * A variable with a decorator
   * @type {number} // Adds type info for JSDoc/IDE
   */
  @test()
  val;

  getX() { /* ... */ }
  getY() { /* ... */ }
  static fromString(str) { /* ... */ }
}

3. Configuring JSDoc to Work with Babel and Decorators #

To get JSDoc to properly recognize your decorated class fields, you need to tell it to use Babel for code parsing. Here's how:

1. Install the jsdoc-babel plugin:

npm install jsdoc-babel --save-dev

2. Create or update your JSDoc config file (jsdoc.json) to match your Babel decorator settings:

{
  "plugins": ["node_modules/jsdoc-babel"],
  "babel": {
    "plugins": [
      ["@babel/plugin-proposal-decorators", { "legacy": false }],
      ["@babel/plugin-proposal-class-properties", { "loose": false }]
    ]
  }
}

Now JSDoc will use Babel to parse your code, correctly identifying field decorators and their associated comments to generate accurate documentation.

内容的提问来源于stack exchange，提问作者HamedFathi