如何在不重写方法的情况下覆盖子类的JSDoc注释？

首先得明确：纯JSDoc本身没有官方支持“不重新声明父类方法就覆盖其注释”的直接方式，因为JSDoc是通过代码结构关联注释的，子类没显式声明方法的话，会直接继承父类的注释信息。不过有两种实用的变通方案：

方案1：轻量重写方法（推荐） #

虽然要重新声明方法，但只写JSDoc和调用父类逻辑的空壳子，完全不影响原有功能，还能完美覆盖注释。比如你的HTTP头集合场景：

/**
 * 通用集合类
 */
class Collection {
  /**
   * 向集合添加元素
   * @param {any} item 要添加的元素
   */
  add(item) {
    // 父类的添加逻辑
    this.items.push(item);
  }
}

/**
 * HTTP头专用集合类
 */
class HttpHeaderCollection extends Collection {
  /**
   * 向集合添加HTTP头
   * @param {HttpHeader} header 要添加的HTTP头
   * @override
   */
  add(header) {
    // 直接调用父类逻辑，不改动原有功能
    super.add(header);
  }
}

这种方式的好处是：JSDoc能精准识别子类的add方法注释，同时完全复用父类的业务逻辑，代码冗余极少。

方案2：利用JSDoc类型扩展（适合强类型场景） #

如果是在TypeScript或类型约束严格的JSDoc环境下，可以通过类型别名+接口实现的方式间接修改注释：

/**
 * @typedef {Object} HttpHeaderCollectionAddFn
 * @property {function(HttpHeader): void} add 向集合添加HTTP头
 */

/**
 * HTTP头专用集合类
 * @augments Collection
 * @implements {HttpHeaderCollectionAddFn}
 */
class HttpHeaderCollection extends Collection {}

不过这种方式兼容性不如方案1，部分JSDoc解析器可能无法完美识别，更适合需要强类型关联的场景。

为啥之前@override、@method没用？ #

@override标签只是标记方法覆盖了父类，但必须和显式声明的方法绑定才会生效；@method标签是给非原型方法（比如静态方法、动态添加的方法）加注释的，对继承来的原型方法无效——你没显式声明方法的话，这些标签找不到对应的方法节点，自然没法替换注释。

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