JavaScript中JSDoc置于类或构造函数前的区别及参数提示问题

我正在使用VSCode（其他代码编辑器情况应一致），在如下代码中，将鼠标悬停在Circle类上时能显示编写的JSDoc内容，但悬停在radius参数上却无法显示。请问问题出在哪里？是否只能将JSDoc写在constructor上方？此前这么做是有效的。简而言之，在构造函数前和类名前定义JSDoc有什么区别？

/**
 * This class represents a circle and can calculate its perimeter and area
 * https://en.wikipedia.org/wiki/Circle
 * @constructor
 * @param {number} radius - The radius of the circle.
 */
export default class Circle {
  contructor(radius) {
    this.radius = radius
  }

  perimeter = () => {
    return this.radius * 2 * Math.PI
  }

  area = () => {
    return Math.pow(this.radius, 2) * Math.PI
  }
}

为什么radius参数的JSDoc不生效？ #

核心问题是你把构造函数的拼写写错了——contructor少了一个c，正确拼写是constructor。VSCode的JavaScript语言服务无法识别这个拼写错误的方法是类的构造函数，因此你写在类JSDoc里的@param标签没法关联到这个参数上，悬停时自然看不到提示。

另外补充：类本身默认就是构造函数，类JSDoc里的@constructor标签其实是多余的，完全可以省略。

类上方和构造函数上方的JSDoc有啥区别？ #

• 类顶部的JSDoc：负责描述整个类的定位、功能，也可以顺带用@param声明构造函数参数（前提是构造函数能被正确识别），还能添加@example、@todo这类标签补充类的整体信息。悬停类名时会显示这部分内容。
• 构造函数顶部的JSDoc：专门针对构造函数的逻辑和参数做说明，比如参数的取值范围、初始化时的特殊处理等。当你悬停构造函数名，或者在调用new Circle()时悬停参数，会显示这部分JSDoc。如果两类JSDoc都写了，VSCode会在参数悬停时优先展示构造函数的JSDoc，类名悬停则展示类的JSDoc。

修复后的代码示例 #

/**
 * 该类表示圆形，可计算其周长和面积
 */
export default class Circle {
  /**
   * 创建圆形实例
   * @param {number} radius - 圆形的半径
   */
  constructor(radius) {
    this.radius = radius
  }

  perimeter = () => {
    return this.radius * 2 * Math.PI
  }

  area = () => {
    return Math.pow(this.radius, 2) * Math.PI
  }
}

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