How to document Promises (using custom tags)

You can use custom tags in Jsdoc2md, for example @bread, @milk, @fulfil, @reject - whatever you like. Custom tags will be rendered as-written in the source comments. There is no standard way to document promises, this is one way to do it using custom tags.

1. Use @fulfil and @reject tags:

/**
 * Returns a promise for something.
 *
 * @returns {Promise}
 * @fulfil {string} - The data you wanted.
 * @reject {Error} - The error `name` property will be one of the following:
 *
 * - `NO_THANKS`: Computer doesn't want to.
 * - `TOO_MUCH`: Too much work, get some other app to do it.
 */
function getSomething () {}

2. Produces output like this:

getSomething() ⇒ Promise

Returns a promise for something.

Kind: global function
Fulfil: string - The data you wanted.
Reject: Error - The error name property will be one of the following:

• NO_THANKS: Computer doesn't want to.
• TOO_MUCH: Too much work, get some other app to do it.