如何在函数注释中描述返回的promise？

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>在我看来,记录是毫无意义的,因为承诺总是拒绝错误 - 指定特定错误的otoh可能有用,但可能有点过分.您的承诺是最终号码的盒装价值.所以正确的方法是将其记录下来.