The JSDoc3 documentation of a function argument is an array of objects?

Question

UseJSDoc.org @type page explains how to document arrays and objects, but not arrays of objects. My function accepts an array of objects with a specific list of properties, and these are the properties that I would like to document.

The function may look like function foo(people) , and the people array could be created by the calling element of the function as

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

I would like to use the syntax {{name: string, profession: string, hitpoints: number}} Person to document objects, but also include the idea that they should be in an array.

Please note that the main object (what I call Person above, although the code will not reference anything like that) is not a proper class, not even named anywhere. And not a single " Person " is defined to use the @ tag.

This complexity of documenting such code with JSDoc3 may seem like a poor organization, and I will gladly consider tips on how to reorganize such ephemeral objects that are primarily used as hash tables (associative arrays).

Answer 1

Here are two ways to do this:

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

Please note that you can tell jsdoc about things that don't actually exist in your code. @typedef is a prime example. I also used @class to document abstract data structures that @typedef cannot handle. I noticed in the documentation that these are pseudo-classes that do not have a corresponding “class” in JavaScript code.