jsdoc 注释应紧贴 `constructor` 方法上方，才能正确为参数（如 `radius`）提供类型提示和悬停文档；类级别的 jsdoc 仅描述类本身，无法关联构造参数。
在 JavaScript 中使用 JSDoc 为 ES2015+ class 添加类型与文档说明时，注释位置至关重要。VS Code 等编辑器依赖 JSDoc 的语义位置来推断类型、生成智能提示（IntelliSense）及悬停文档。若将 JSDoc 写在 class 声明前（如问题中所示），编辑器仅能识别该注释用于描述整个 Circle 类，而不会将其参数（@param radius）绑定到构造函数签名上——因此悬停 radius 时无提示。
✅ 正确做法：将 JSDoc 放在 constructor 方法正上方：
/**
* Represents a circle and provides methods to calculate its perimeter and area.
* @see https://en.wikipedia.org/wiki/Circle
*/
export default class Circle {
/**
* Creates a new Circle instance.
* @param {number} radius - The radius of the circle. Must be positive.
*/
constructor(radius) {
if (radius <= 0) throw new Error('Radius must be a positive number');
this.radius = radius;
}
perimeter() {
return this.radius * 2 * Math.PI;
}
area() {
return Math.pow(this.radius, 2) * Math.PI;
}
}⚠️ 注意事项：
- 移除 @constructor 标签：ES2015 class 语法下，JSDoc 可自动识别 constructor 方法，显式添加 @constructor 不但冗余，还可能干扰解析（尤其在某些工具链中）；
- 避免在类注释中写 @param：@param、@returns 等参数/返回值标签必须出现在函数（含 constructor）的 JSDoc 中，否则 JSDoc 解析器无法建立参数与形参的映射；
- 方法定义建议用普通函数语法：问题中使用了箭头函数赋值（perimeter = () => { ... }），虽可行，但会丢失 this 绑定灵活性，且部分类型工具（如 TypeScript 或 JSDoc + Closure Compiler）对类字段箭头函数的类型推导支持较弱；推荐使用标准方法定义（如 perimeter() { ... }）以获得更佳 IDE 支持；
- 补充运行时校验可提升健壮性：如示例中对 radius 的正数检查，配合 JSDoc 的 @param 描述，形成「文档 + 类型 + 行为」三重保障。
总结：JSDoc 是面向“被注释的代码元素”生效的——类注释描述类，构造函数注释描述构造行为及参数。精准定位注释位置，是解锁现代 JavaScript 工具链（VS Code、TypeScript、ESLint、typedoc 等）智能能力的关键前提。
立即学习“Java免费学习笔记（深入）”；
