When developing with Promise in JavaScript, the documentation may be a hard point. Here is how I do, when documenting code with YUIDoc:

/**
 * ...
 * @method doSomething
 * @param {Object} pOptions The Options
 * @return {Promise|Object} A promise of the result that returns an object in case of success
 * @static
 */

The trick is to only specify the return type when the promise is resolved. When the promise is rejected, the return type is always an Error or a subclass of Error. Moreover, by using a | character, both the Promise type and the return type are clickable.

This tip was first spotted in the following StackOverflow comment.