如何使用JSDoc为继承自外部包父类的类库类记录继承方法文档？

刚好我在开发类库时也碰到过一模一样的问题——不想为了凑文档写一堆空的super调用，下面几个方案应该能帮你优雅解决：

1. 用JSDoc的@inheritDoc标签（纯JS场景） #

如果你的文档生成工具支持JSDoc 3及以上版本，可以直接通过@inheritDoc标签继承父类方法的文档，完全不需要写冗余的方法体。示例如下：

/**
 * @augments ExternalParentClass
 * @inheritDoc ExternalParentClass#doThis
 */
class MySubClass extends ExternalParentClass {
  // 只写你的自定义方法即可
  myCustomMethod() {
    // ...
  }
}

这里的@augments用来明确子类和父类的继承关系，@inheritDoc指定要继承文档的父类方法。只要外部包的JSDoc能被当前项目的文档工具识别（比如把外部包的源码或类型定义加入JSDoc的扫描路径），就能自动把父类的方法文档同步到子类文档里。

2. TypeScript + TypeDoc（推荐方案） #

如果你用TypeScript开发类库，TypeDoc默认会自动继承父类的方法文档，根本不需要额外配置。只要子类正确extends了外部父类，TypeDoc生成文档时会自动把父类的所有公共/受保护方法、属性的文档都包含进来。示例：

import { ExternalParentClass } from 'external-package';

export class MySubClass extends ExternalParentClass {
  /**
   * 这是子类的自定义方法
   */
  public myCustomMethod(): void {
    // ...
  }
}

最终生成的文档里，MySubClass会同时展示myCustomMethod和从ExternalParentClass继承来的doThis等方法，全程不用写多余代码。

3. 利用你作为外部包作者的优势 #

既然你同时是外部父类的作者，还可以从源头优化，让依赖它的类库更方便地继承文档：

• 在外部父类的JSDoc里加上@module标签，明确模块归属
• 给父类的方法统一加上@public或@protected标签，让文档工具清晰识别可继承的成员
• 完善外部包的类型定义（.d.ts）文件，这样即使是纯JS项目，也能通过类型定义读取父类的文档

临时过渡方案（不推荐但有用） #

如果暂时无法切换到上述方案，也可以用条件编译的方式，只在开发环境添加空方法体，生产环境自动剔除：

class MySubClass extends ExternalParentClass {
  /**
   * This is a method that's actually inherited from the parent class.
   */
  #ifdef DEV
  doThis() { super.doThis(); }
  #endif

  // 自定义方法...
}

不过这只是权宜之计，还是推荐前面的JSDoc/TypeDoc方案更优雅。

内容的提问来源于stack exchange，提问作者djip.co