使用jsdoc定义递归对象形状的标准方法？

Question

我正在使用 jsdoc 来记录函数参数。一个函数是递归的，并接受一组可以嵌套到任意深度的对象。这是一个简化的示例：

const person = {
    firstName: "Bob",
    lastName: "Smith",
    children: [{ firstName: "Bill", lastName: "Smith", children: [......] }] // an array of person shaped objects with values for firstName, lastName, and children
}

我尝试写这样的东西，但我不确定如何处理递归。有没有一种简单的方法可以做到这一点，或者我必须为此对象定义一个类？

/**
* @param person {{ firstName: string, lastName: string, children: person[] }}
*                                                                 ^ this doesn't work
*/

我只是使用

person

作为示例 - 在我的实际应用程序中，它是一个表示带嵌套的项目符号文本的对象。

Answer 1

您可以使用

@typedef

标签 来定义类型。它还支持递归类型。

您的 JSDoc 可能如下所示：

/**
 * @typedef Person
 * @type {object}
 * @property {string} firstname
 * @property {string} lastname
 * @property {Person[]} children
 */

/**
 * @param {Person} person
 */

或更短（但可能可读性较差）：

/**
 * @typedef {{firstname: string, lastname: string, children: Person[]}} Person
 */

/**
 * @param {Person} person
 */

注意：您可能需要关注microsoft/TypeScript

存储库

的问题#46011（标题为“支持选择退出jsdoc

@typedef

导出”）。