如何使用 JSDoc 记录扩展另一个 class 类型的 class 参数？

Question

假设我有这个 javascript 定义 class 的代码。它的静态方法之一 returns a class 用于实例化子项。

class ParentClass {
  /**
   * Creates an instance of parent class
   *
   * @param {string} type - the type of the instance.
   */
  constructor(type) {
    this.type = type;
  }

  /**
   * Creates a child class.
   *
   * @param {string} type - the type.
   *
   * @returns {class<ParentClass> ?? ----- WHAT GOES HERE?? -----} the resulting class.
   */
  static createChildClass(type) {
    return class extends ParentClass {
      constructor() {
        super(type);
      }
    };
  }

}

我正在使用 eslint 插件 eslint-plugin-jsdoc 检查代码中的 JSDoc 注释。

我的问题是：记录类型（在 @param 或 @returns 中）的正确方法是什么，它是从另一个 [=23= 扩展的 class ]？换句话说，我如何记录上面代码中标记的@returns？

Answer 1

jsdoc does not document 表示扩展 class.

类型的任何特殊语法

一方面，您可能只使用 ParentClass 作为类型（暗示此接口就是 returned）——考虑到 jsdoc 实际上是一个文档工具，而不是比严格的类型检查器（和 JavaScript 方法更经常地不仅仅是期望一个特定的（duck-typable）接口而不是强加 instanceof 检查等）。

但是，您可以像这样使用 @augments tag (also available in jsdoc as @extends, and required as such in Closure):

为您的 return 类型给出更精确的定义

class ParentClass {

  // ...

  /**
   * Creates a child class.
   *
   * @param {string} type - the type.
   *
   * @returns {ChildClass} the resulting class.
   */
  static createChildClass(type) {
    /**
     * @class ChildClass
     * @augments ParentClass
     */
    return class extends ParentClass {
      constructor() {
        super(type);
      }
    };
  }
}

（IIRC，虽然 jsdoc 没有记录使用 @extends 的括号，因为 Closure 显然需要，但我相信它可能与括号一起使用。）

请注意，这仍然有点 hack，但是，因为我们没有记录特定的实例是 returned，但我们想记录整个 class 是 returned。有关未实现的问题，请参阅 https://github.com/jsdoc/jsdoc/issues/1349。（TypeScript 允许 typeof 带有类型，例如 @returns {typeof ChildClass}。）

如何使用 JSDoc 记录扩展另一个 class 类型的 class 参数？

How to document parameter of class type extending another class with JSDoc?

javascript

jsdoc

eslint