How to specify resolution and rejection type of the promise in JSDoc?

Question

I have some code that returns a promise object, e.g. using Q library for NodeJS.

var Q = require(\'q\');

/**
 * @returns          


        

Answer 1

I tend to define an external type for the promise:

/**
* A promise object provided by the q promise library.
* @external Promise
* @see {@link https://github.com/kriskowal/q/wiki/API-Reference}
*/

Now you can describe in the @return statement of your function documentation what happens to the promise:

/**
* @return {external:Promise}  On success the promise will be resolved with 
* "some result".

* On error the promise will be rejected with an {@link Error}.
*/
function task(err) {
    return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}