Add the promised return type to JSDoc Promise annotations

[Jaifroid]

I've found myself puzzling over how to document the returned value of a function when the function is a Promise for a specific value. Should we do

@returns {Promise} A Promise for an array or an error object if the Promise throws

or

@returns {Array} A Promise for an array...

There is little clear / official guidance, but conventions have been adopted. There is one sole example of a syntax that addresses this in JSDoc: https://jsdoc.app/tags-async.html . The example looks like this:

/**
 * Download data from the specified URL.
 *
 * @async
 * @function downloadData
 * @param {string} url - The URL to download from.
 * @return {Promise<string>} The data from the URL.
 */

Which suggests we should use, e.g., @returns {Promise<Array>}, which is what I've adopted finally in #556. As well as documenting the resolved case, we could also add @throws {Error} to cover the rejected case (but only worth doing if the rejected value is used/meaningful in some way). [NB The correct keyword is @returns not @return, the example has a typo in the original.]

There is a long discussion about the right way to do this in the still open issue https://github.com/jsdoc/jsdoc/issues/509 , with one comment adding:

In VS Code and TypeScript, it’s possible to use @return {Promise<T>}, where T is the type of the resolved value.

The maintainer (or at least admin at JSDoc), hegemonic, replies:

That’s also the recommended syntax in JSDoc.

Since this is a valid TypeScript type definition as well, it would seem sensible to document at least resolved values in Promise return types in our JSDoc annotations. This is clearly not urgent.