子类未重写父类baseMethod时，如何补充JSDoc参数要求说明？

虽然子类B和C没有重写baseMethod的核心逻辑，但我们可以通过JSDoc的特性，为每个子类继承来的baseMethod补充专属的参数说明，让IDE和其他开发者能清晰知晓不同子类的方法调用要求。下面是几种实用的方案：

方案1：轻量重写方法并补充JSDoc #

这种方式最直观，我们不改变方法的原有逻辑，仅通过重写方法并调用super.baseMethod()，就能直接在方法上添加子类专属的JSDoc。好处是IDE能直接识别并给出参数提示：

/**
 * 类B，继承自A
 * @extends A
 */
class B extends A {
  constructor() {
    super(); // 注意：ES6子类构造函数必须先调用super才能访问this
    this.baseMethodValidator = function () {
      // ... B validation
    };
  }

  /**
   * 执行B实例的基础操作，必须传入id和name参数
   * @override
   * @param {string} id - 实例的唯一标识（必填）
   * @param {string} name - 实例的名称（必填）
   * @return {void}
   * @throws {TypeError} 如果参数缺失、类型错误或验证失败
   */
  baseMethod() {
    super.baseMethod(); // 完全复用父类逻辑
  }
}

/**
 * 类C，继承自A
 * @extends A
 */
class C extends A {
  constructor() {
    super();
    this.baseMethodValidator = function () {
      // ... C validation
    };
  }

  /**
   * 执行C实例的基础操作，仅需传入id参数
   * @override
   * @param {string} id - 实例的唯一标识（必填）
   * @return {void}
   * @throws {TypeError} 如果参数缺失、类型错误或验证失败
   */
  baseMethod() {
    super.baseMethod();
  }
}

方案2：在类级JSDoc中用@method标注继承方法 #

如果不想额外编写方法体，可以在子类的类级JSDoc里，用@method直接描述继承来的baseMethod的参数要求：

/**
 * 类B，继承自A
 * @extends A
 * @method baseMethod
 * @param {string} id - 实例的唯一标识（必填）
 * @param {string} name - 实例的名称（必填）
 * @return {void}
 * @throws {TypeError} 如果参数缺失、类型错误或验证失败
 */
class B extends A {
  constructor() {
    super();
    this.baseMethodValidator = function () {
      // ... B validation
    };
  }
}

/**
 * 类C，继承自A
 * @extends A
 * @method baseMethod
 * @param {string} id - 实例的唯一标识（必填）
 * @return {void}
 * @throws {TypeError} 如果参数缺失、类型错误或验证失败
 */
class C extends A {
  constructor() {
    super();
    this.baseMethodValidator = function () {
      // ... C validation
    };
  }
}

方案3：用属性引用方式补充JSDoc #

这种方式更简洁，直接在子类中引用继承的方法并添加JSDoc，不需要编写方法体：

/**
 * 类B，继承自A
 * @extends A
 */
class B extends A {
  constructor() {
    super();
    this.baseMethodValidator = function () {
      // ... B validation
    };
  }

  /**
   * 执行B实例的基础操作，必须传入id和name参数
   * @inheritDoc
   * @param {string} id - 实例的唯一标识（必填）
   * @param {string} name - 实例的名称（必填）
   */
  baseMethod;
}

/**
 * 类C，继承自A
 * @extends A
 */
class C extends A {
  constructor() {
    super();
    this.baseMethodValidator = function () {
      // ... C validation
    };
  }

  /**
   * 执行C实例的基础操作，仅需传入id参数
   * @inheritDoc
   * @param {string} id - 实例的唯一标识（必填）
   */
  baseMethod;
}

关键注意点 #

• 务必在子类构造函数中调用super()，否则会抛出ReferenceError，这是ES6类继承的强制要求，原代码中遗漏了这一步哦。
• 三种方案都能让IDE（比如VS Code）正确提示参数信息，选择哪种取决于你的代码风格偏好：追求直观选方案1，追求简洁选方案3，类级统一说明选方案2。

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