How to document resolved values of JavaScript promises

问题

Given this code :

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

How can I document that asyncFoo will return a Promise that, when fulfilled will yield an instance of Bar, and when rejected will yield an instance of Error?

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

回答1:

Looks like you should do the following, based on some other source code's comments.

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

How JavaScript Promises are documented.

Similar question with a similar answer. Note the lack of a dot in that answer.

回答2:

I like to specify that it's an async function with @async and specify the fulfilled return with @returns and error with @throws

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

来源：https://stackoverflow.com/questions/35869160/how-to-document-resolved-values-of-javascript-promises