如何在函数注释中描述返回的承诺

Question

在编写JavaScript代码时，我总是像这里描述的那样注释我的函数，如:

/**
 * Add two values
 * @param {Number} a
 * @param {Number} b
 * @returns {Number} the sum of a and b
 */
function add(a, b) {
  return a + b;
}

现在，当我写一个返回Promise的异步函数时，这将是:

/**
 * Add two values
 * @param {Number} a
 * @param {Number} b
 * @returns {Promise} the sum of a and b
 */
function add(a, b) {
  return new Promise(function (resolve, reject) {
    resolve(a + b);
  });
}

但是现在返回类型(Promise)的描述缺少关于Promise解析时返回什么类型的信息。

如何表示返回的承诺将与Number解析?

我认为Promise.<Number>是最好的(类似于Array.<Number>)，但在这方面没有发现任何常见的做法

Answer 1

您需要的是泛型。虽然jsdoc还没有正式支持它，但这是处理它的正确方法。

正确的方法是:Promise.<number> .

在我看来，记录Promise.<number, Error>是毫无意义的，因为一个承诺总是伴随着一个错误而拒绝——虽然指定特定的错误可能是有用的，但可能是多余的。你的承诺是一个最终数字的框值。所以正确的方法是这样记录。