VSCode: How to document promise that resolves with complex object?

Question

I have a function f that returns a Promise. The returned Promise either resolve({name: String, data: Object}) or reject(Error).

I've tried the following syntax(as mentioned in an issue in JSDoc) in VSCode, but it doesn't work:

/**
 * @promise fPromise
 * @reject {Error}
 * @fulfill {Object} project
 * @fulfill {Object} project.data
 * @fulfill {String} project.name
 * @returns fPromise
*/

Answer 1

I think your best bet is to wrap your fulfill response into a custom object:

/**
 * @promise fPromise
 * @reject {Error}
 * @fulfill {Project}
 * @returns {Promise.<Project>}
*/
function renderResults(data) {
    return new Promise((resolve, reject) => {
        resolve(new Project())
    })
}

renderResults()

function Project() {
    this.data = "data";
    this.name = "project phoenix"
    this.location = {
        city: 'seattle',
        state: 'wa'
    }
}

This will show in VS Code like this:

Answer 2

To be as clear as possible, why not put the nature of the object on a single line for the description? Its just supposed to be a description of that fulfill.

/**
 * @promise fPromise
 * @fulfill {Object} A project object with the format {name: String, data: Object}
 * @reject {Error}
 * @returns fPromise
*/

Or, if you want to handle dynamically generated object keys, similar to the Google Style Guide:

/**
 * @promise fPromise
 * @fulfill {Object.<String, Object>} 
 * @reject {Error}
 * @returns fPromise
*/

That allows anyone reading your comment to understand what the returned object looks like, what the keys are, and what type of value should be in each key.

Unless, you're trying to say that it can return any of the three possibilities. Then I think your original format is a little bit more descriptive of the possible results of the Promise being fulfilled.