如何记录 JavaScript 承诺的已解决值

Question

鉴于此代码：

function asyncFoo() {
  return new Promise(function (fulfill, reject) {
    doAsyncStuff(function(err, data) {
      if(err) reject(new Error(err));
      else fulfill(new Bar(data));
    });
  });
}

我如何记录 asyncFoo 将 return 一个 Promise，当满足时将产生一个 Bar 的实例，而当被拒绝时将产生一个实例Error？

/**
 * @return << Here, what do I have to write? >>
 */
function asyncFoo() { ... }

Answer 1

根据 some other source code's comments。

看来您应该执行以下操作

/**
 * @return {Promise.<Bar>}
 */

How JavaScript Promises are documented.

Similar question with a similar answer. 请注意该答案中缺少一个点。

Answer 2

我想用 @async 指定它是一个异步函数，用 @returns 指定完成的 return 和用 @throws

指定错误

/**
 * @async
 * @returns {Bar}
 * @throws {Error}
 */
function asyncFoo() { ... }

Answer 3

我个人更喜欢严格区分 - 从异步函数声明最终类型，从直接 returns Promise 的函数声明 Promise。

/**
  Async JSON request
  @param {string} sql
  @returns {object}
*/
async function request(sql)
{
  return JSON.parse(await dbEngine.executeRequest(sql));
}

/**
  Async JSON request
  @param {string} sql
  @returns {Promise<string>}
*/
function request(sql)
{
  return dbEngine.executeRequest(sql);
}

如何记录 JavaScript 承诺的已解决值

How to document resolved values of JavaScript promises

javascript

jsdoc