使用 JSDoc 注释通用 ES6 类

Question

我想用 JSDoc 记录一个通用的类似地图的数据结构。首先，请注意该结构不会扩展Map。

\n\n

一个更普遍的问题是：如何正确注释通用 ES6 类构造？

\n\n

考虑以下代码。注释的标记部分会在注释中产生错误。

\n\n

/** @type {MyMap<string, number>} */\n//         ^^^^^^^^^^^^^^^^^^^^^ [js] Type 'MyMap' is not generic.\nconst map = new MyMap();\n

\n\n

\xe2\x80\x99 的定义是MyMap：

\n\n

// @ts-check\n\n/**\n * @template K, V\n */\nclass MyMap {\n  constructor() {\n    this._map = new Map();\n  }\n}\n

\n\n

我需要做什么才能MyMap算作泛型类型？如何将K和公开V为结构的通用类型？

\n\n

// @ts-check（注意：我使用 Visual Studio Code 通过添加到 JavaScript 文件顶部来验证注释。）

\n

Answer 1

首先，正如问题中所述，@template使MyMap类通用的注释已经是正确的。下面MyMap有两个通用类型Key和Value。这些类型可以在类内部使用，例如，通过将实例属性的类型设置this._map为/** @type {Map<Key, Value>} */等。为了演示，我添加了两个依赖于这些类型的简单包装Map.prototype.set方法Map.prototype.get。

// @ts-check

/**
 * @template Key, Value
 */
class MyMap {
  constructor() {
    /** @type {Map<Key, Value>} */ this._map = new Map();
  }

  /**
   * @param {Key} key 
   * @param {Value} value 
   */
  set(key, value) {
    this._map.set(key, value)
  }

  /**
   * @param {Key} key 
   * @returns {Value | undefined}
   */
  get(key) {
    return this._map.get(key)
  }
}

/** @type {MyMap<string, number>} */ const map = new MyMap();
map.set('key', 1)
map.get('key')