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

Here is what I like to do (which may be a little overdone):

/**
 * @external Promise
 * @see {@link http://api.jquery.com/Types/#Promise Promise}
 */

/**
 * This callback is called when the result is loaded.
 *
 * @callback SuccessCallback
 * @param {string} result - The result is loaded.
 */

/**
 * This callback is called when the result fails to load.
 *
 * @callback ErrorCallback
 * @param {Error} error - The error that occurred while loading the result.
 */

/**
 * Resolves with a {@link SuccessCallback}, fails with a {@link ErrorCallback}
 *
 * @typedef {external:Promise} LoadResultPromise
 */

/**
 * Loads the result
 *
 * @returns {LoadResultPromise} The promise that the result will load.
 */
function loadResult() {
    // do something
    return promise;
}

Basically, define the base promise with a link to some documentation (in this case I am linking to the jQuery one), define your callbacks that will be called when the promise either resolves or fails, then define your specific promise which links back to the callback documentation.

Finally, use your specific promise type as the return type.