How to specify an array of objects as a parameter or return value in JSDoc?

javascript documentation jsdoc
Ray picture Ray · Jan 30, 2013 · Viewed 68.9k times · Source

In JSDoc, the best documentation I can find shows to use the following if you have an array of a specific type (such as an array of strings) as:

/**
 * @param {Array.<string>} myStrings All my awesome strings
 */
 function blah(myStrings){
     //stuff here...
 }

How would you replace the below question marks specify an array of objects?

/**
 * @param {???????} myObjects All of my equally awesome objects
 */
 function blah(myObjects){
     //stuff here...
 }

Answer

Rene Saarsoo picture Rene Saarsoo · Feb 13, 2013

You should be more specific what you mean by JSDoc - this is a generic term covering pretty much all the JavaDoc-style documentation tools for JavaScript.

The syntax you used for array of strings looks like the one supported by Google Closure Compiler.

Using this, an array of Objects would be:

/**
 * @param {Array.<Object>} myObjects
 */

Or just an array of anything - this should work with pretty much all doc tools:

/**
 * @param {Array} myArray
 */

jsdoc-toolkit, JSDoc 3, and JSDuck support the following syntax to denote an array of objects:

/**
 * @param {Object[]} myArray
 */

EDIT

In case you know the keys and the variable type of the values you can also do:

/**
 * @param {Array.<{myNumber: Number, myString: String, myArray: Array}>} myObjects
 */

or

/**
 * @param {{myNumber: Number, myString: String, myArray: Array}[]} myObjects
 */

Related questions

Best way to document anonymous objects and functions with jsdoc

Edit: This is technically a 2 part question. I've chosen the best answer that covers the question in general and linked to the answer that handles the specific question. What is the best way to document anonymous objects and functions with …

Read More
How to specify resolution and rejection type of the promise in JSDoc?

I have some code that returns a promise object, e.g. using Q library for NodeJS. var Q = require('q'); /** * @returns ??? */ function task(err) { return err? Q.reject(new Error('Some error')) : Q.resolve('Some result'); } How to document such …

Read More
JSDoc adding real code in documentation

Do you know if there is some sort of <code /> tag in JSDoc? I need to add pieces of code in my documentation like this: /** * This function does something see example below: * * var x = foo("test"); //it will …

Read More