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

Question

我有一个函数 f returns 一个 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
*/

Answer 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
*/

这样一来，阅读您评论的任何人都可以了解 returned 对象的外观、键是什么以及每个键中的值类型。

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

Answer 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 中显示如下：

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

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

documentation

jsdoc

visual-studio-code