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() { ... }
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.
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() { ... }
{Bar} nor does it throw {Error}
async function Use JSDoc: @async
async if it can be invoked with the await keyword. The @async annotation is needed for functions not declared with the async keyword but do return a promise.{Promise<string>}There seems to be no way to declare what can be thrown, neither through @ directives nor through the Promise generic parameters (see Typescript Promise rejection type).
Per documentation at https://jsdoc.app/ your code should look like:
/**
* @returns {Promise<Bar>}
*/
function asyncFoo() {
return new Promise(function (fulfill, reject) {
doAsyncStuff(function(err, data) {
if(err) reject(new Error(err));
else fulfill(new Bar(data));
});
});
}
I personally prefer strict differentiation - declare final type from async function and Promise from a function that directly returns 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);
}
