16

I have an array that looks like this:

[{
    "name": "c917379",
    "email": "[email protected]"

},
{
    "name": "c917389",
    "email": "[email protected]"
}]

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?

Improve this question
6
  • JSON is what you get when you serialize the data to a JSON text. It is just an array of objects in JavaScript. Commented Jun 18, 2013 at 8:25
  • i know. but i am wondering how you would document it in JSDoc. I know JSDoc can document method types, and anonymous objects Commented Jun 18, 2013 at 8: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 Commented Jun 18, 2013 at 8:35
  • 1
    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. Commented Jun 18, 2013 at 8:41
  • 3
    possible duplicate of Document collection (array of type) return value and parameter in JSDoc Commented Aug 21, 2015 at 12:08

4 Answers 4

Reset to default
30

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}>}
Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

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}[]}.
@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.<SomeType> as "Array of SomeType" e.g. Array of String, Array of Person.
I agree with @MichaelLiquori that this syntax is easier to read then the syntax with the square brackets @param {Array.<{name:string, email:string}>}
25

I just figured out the answer to my question :

It would look like this :

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

7 Comments

how does that scale if you had lots of fields?
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
If JSDoc permits it, then, I suggest you add a , ... inside that specification
u mean @param {{name:string, email:string, ...}[]}? Webstorm doesnt like it
thanks for your help :) in any case my method is only interested in these two values. Not sure what that would bring anyway.
|
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 ;-)

Improve this answer

5 Comments

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.
ah, so you've no opportunity to massage the objects from "plain old data" into something nicer, first?
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.
@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.
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[]}?
2

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
 * */
Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.