VSCode：如何记录用复杂对象解析的承诺？答案

【问题标题】：VSCode: How to document promise that resolves with complex object?VSCode：如何记录用复杂对象解析的承诺？
【发布时间】：2018-01-18 16:38:38
【问题描述】：

我有一个函数f，它返回一个Promise。返回的Promise 或者resolve({name: String, data: Object}) 或reject(Error)。

我在 VSCode 中尝试了以下语法（如 an issue in JSDoc 中所述），但它不起作用：

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

【问题讨论】：

标签： documentation visual-studio-code jsdoc

【解决方案1】：

为了尽可能清楚，为什么不将对象的性质放在一行中进行描述？它只是应该是对实现的描述。

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

或者，如果你想处理动态生成的对象键，类似于Google Style Guide：

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

这让任何阅读您评论的人都可以了解返回的对象是什么样子、键是什么以及每个键中应该包含什么类型的值。

除非，您想说它可以返回三种可能性中的任何一种。那么我认为您的原始格式更能描述 Promise 实现的可能结果。

【讨论】：

在我的例子中，实现 promise 的结果可能包含 10+ 个静态键，因此在一行中记录它们是不方便的。

【解决方案2】：

我认为您最好的选择是将您的 fulfill 响应包装到自定义对象中：

/**
 * @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'
    }
}

这将在 VS Code 中显示如下：

【讨论】：