函数参数的 JSDoc3 文档是对象数组？答案

【问题标题】：JSDoc3 documentation of a function's argument being an array of objects?函数参数的 JSDoc3 文档是对象数组？
【发布时间】：2023-03-24 11:58:01
【问题描述】：

UseJSDoc.org 的@type 页面解释了如何记录数组和对象，而不是数组of 对象。我的函数接受具有特定属性列表的对象数组，而我想要记录的正是这些属性。

函数可能看起来像function foo(people)，而people 数组可能是由函数的调用者创建的

arr = [];
arr.push({name: "Alfred", profession: "Butler", hitpoints: 2});
arr.push({name: "Batman", profession: "Vigilante", hitpoints: 42});
// ...
foo(arr)

我想使用 {{name: string, profession: string, hitpoints: number}} Person 语法来记录对象，但也包括它们必须位于数组中的概念。

请注意，底层对象（我在上面称为Person，尽管代码不会引用任何东西）不是一个合适的类，甚至没有在任何地方命名。我也没有在任何地方定义一个“Person”来使用@property标签。

用 JSDoc3 记录这种代码的困难可能表明组织不好，我很乐意考虑如何重组像这样的临时对象，主要用作哈希表（关联数组）。

【问题讨论】：

标签： javascript arrays object jsdoc jsdoc3

【解决方案1】：

这里有两种方法：

/**
 * @param {Array.<{name: string, profession: string, hitpoints: number}>} people The people.
 */
function foo(people) {
}

/**
 * @typedef Person
 * @property {string} name
 * @property {string} profession
 * @property {number} hitpoints
 */

/**
 * @param {Array.<Person>} people The people.
 */
function foo2(people) {
}

请注意，您可以告诉 jsdoc 您的代码中实际上不存在的内容。 @typedef 就是一个很好的例子。我还使用@class 记录@typedef 无法处理的抽象数据结构。我在文档中注意到这些是伪类，在 JavaScript 代码中没有任何对应的“类”。

【讨论】：