How do you document an array of objects as a parameter in JSDoc?

Question

I have an array that looks like this:

[{
    "name": "c917379",
    "email": "jim@bmw.de"

},
{
    "name": "c917389",
    "email": "jane@bmw.de"
}]

It is an array of arbitrary length with a number of repeating fields (I've reduced this to two fields for clarity). This gets passed into a JavaScript method.

/**
 * @param {?}  data
 */
update:  function(data) {...}

I was wondering how you would document this in JSDoc. Ie. how would you document the type where the question mark is?

JSON is what you get when you serialize the data to a JSON text. It is just an array of objects in JavaScript. — Quentin, Jun 18 '13 at 08:25
i know. but i am wondering how you would document it in JSDoc. I know JSDoc can document method types, and anonymous objects — Oliver Watkins, Jun 18 '13 at 08:25
i dont understand your edit. JSON is the javascript representation of a data structure. I think you need at least one mention of JSON in the question — Oliver Watkins, Jun 18 '13 at 08:35
JSON is *not* "the JavaScript representation of a data structure". It is a separate data format based on a subset of JavaScript. — Quentin, Jun 18 '13 at 08:35
You are confusing JSON with object literals (a common mistake). JSON is a data format like XML or CSV. Object literals is a specific syntax structure to define objects in JavaScript source code. They look similar, but are completely different. — Felix Kling, Jun 18 '13 at 08:41
possible duplicate of [Document collection (array of type) return value and parameter in JSDoc](http://stackoverflow.com/questions/8498975/document-collection-array-of-type-return-value-and-parameter-in-jsdoc) — Gajus, Aug 21 '15 at 12:08

Wilt · Answer 1 · 2020-10-09T18:27:26.553

29

In JSDoc there is an example given for an array with members of type MyClass. It looks like this:

@param {Array.<MyClass>}

So then you can also do like this:

@param {Array.<Object>}

And then this also makes sense:

@param {Array.<{name:string, email:string}>}

edited Oct 09 '20 at 18:27

answered Apr 01 '14 at 13:24

Wilt

41,477
12
152
203

1

Why is this not higher voted? Although the angle brackets are a little weird, I feel that the `[]` format is not easily seen. _Especially_ when it comes to longer cases such as `{a: number, b: string, c}[]}`. – Michael Liquori Mar 14 '16 at 02:00
1

@mliqu The angled brackets represent a generic type parameter. It's a very common syntax. The [] is represented already by the word Array. You should read Array. as "Array of SomeType" e.g. Array of String, Array of Person. – charles-allen Jul 06 '16 at 15:44
1

I agree with @MichaelLiquori that this syntax is easier to read then the syntax with the square brackets `@param {Array.<{name:string, email:string}>}` – magikMaker Nov 23 '17 at 13:39

score 25 · Accepted Answer · answered Jun 18 '13 at 08:40

25

I just figured out the answer to my question :

It would look like this :

/**
 *
 * @param {{name:string, email:string}[]}  
 *
 */

answered Jun 18 '13 at 08:40

Oliver Watkins

12,575
33
119
225

1

how does that scale if you had lots of fields? – Alnitak Jun 18 '13 at 08:41
1

The method is only interested in these two fields. The data object may have other fields, but the requirement is that these two fields exist in the array – Oliver Watkins Jun 18 '13 at 08:42
If JSDoc permits it, then, I suggest you add a `, ...` inside that specification – Alnitak Jun 18 '13 at 08:44
2

u mean @param {{name:string, email:string, ...}[]}? Webstorm doesnt like it – Oliver Watkins Jun 18 '13 at 08:46
thanks for your help :) in any case my method is only interested in these two values. Not sure what that would bring anyway. – Oliver Watkins Jun 18 '13 at 08:48
The intent was to indicate that it's _not an error_ if additional keys exist in those objects. – Alnitak Jun 18 '13 at 09:58
@OliverWatkins: To scale you should consider breaking out the object definition to a separate block using [`@typedef`](http://usejsdoc.org/tags-typedef.html). – Michael Liquori Aug 26 '16 at 18:51

score 10 · Answer 3 · answered Jun 18 '13 at 08:36

10

Since there's nothing intrinsically "special" with your object contents I believe you would just have to declare it as:

@param {Object[]} data

The alternative would be to declare a "proper" constructor function for your "class", and then replace Object with that function name.

This encapsulation might also help other parts of your code ;-)

answered Jun 18 '13 at 08:36

Alnitak

334,560
70
407
495

this is an ajax callback object, so even if i did send it to a constructor i would like to document the type that i am passing in. – Oliver Watkins Jun 18 '13 at 08:41
ah, so you've no opportunity to massage the objects from "plain old data" into something nicer, first? – Alnitak Jun 18 '13 at 08:42
yeah i would like to massage it into some object first and just have that as the param {MYMassagedObjects[]}, but refactoring JS is hell, and i dont think they would let me do such a change. – Oliver Watkins Jun 18 '13 at 08:45
@OliverWatkins if you happen to be using jQuery and `.done` style callbacks then the `.then` method is a handy means to preprocess results before passing them onto the original callbacks. – Alnitak Jun 18 '13 at 08:46
If PHPDoc allows you to document an object like this `@param {{a: number, b: string, c}}` instead of `@param {Object}` then why should you not document an array like this: `@param {{a: number, b: string, c}[]}` instead of `@param {Object[]}`? – Wilt Nov 16 '15 at 08:30

score 2 · Answer 4 · answered Jul 08 '19 at 14:13

Since this is the first question that appears on Google, i think that is useful show how to documment an two dimensional array.

The default sintax doesn't work, it shows like 'JsDoc sinxtax error':

/**
 * @param {Object[][]} a two dimensional array of object
 * */

The correct way to signal a two dimensional array is:

/**
 * @param {Array.<Array.<Object>>} a two dimensional array of object
 * */

How do you document an array of objects as a parameter in JSDoc?

4 Answers4

Linked