Questions about documenting nested array and object data with jsDoc

Question

How do I format nested arrays and objects using jsdoc?

This is my best guess:

an_obj = { 
        username1 : [
            {
                param1 : "value 1-1-1",
                param2 : "value 1-1-2",
                optional_nested : "1-1--2"
            },
            {
                param1 : "value 1-2-1",
                param2 : "value 1-2-2"
            },
        ],
        username2 : [
            {
                param1 : "value 2-1-1",
                param2 : "value 2-1-2"
            },
            {
                param1 : "value 2-2-1",
                param2 : "value 2-2-2",
                optional_nested : "2-2--2"              

            }
        ]
    }
}


/**
 * A function description.
 * @param {Object} obj
 * @param {Object} obj.username  This is not the object name, but a name type. 
 * @param {Array}  obj.username.array Desc...  using [] would conflict with optional params.
 *                                    However this could be confused with an object called array.
 * @param {String} obj.username.array.param1 Desc... This is the object name rather than a type.
 * @param {String} obj.username.array.param2 Desc... 
 * @param {String} obj.username.array.[optional_param] Desc... 
 */
var myFunc = function(obj){
    //...
};
myFunc(an_obj);

How do I indicate that an object is indexed by a kind of string?

How do I define a nested array?

Also not sure where to put the square brackets in the optional parameter.

Armel Larcier · Accepted Answer · 2012-08-09 10:17:43Z

1

You can try doing it like this : (as specified here http://code.google.com/p/jsdoc-toolkit/wiki/TagParam)

/**
* @param {String[]} obj.username.array
*/

This is supposed to declare obj.username.array as an array of strings. Are you using jsdoc or jsdoc3?

answered Aug 9, 2012 at 10:17

Armel Larcier

16k7 gold badges70 silver badges89 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

GorillaMoe Over a year ago

I'm currently using jsdoc-toolkit v3. I can't figure out how to deal with something like this {id: 'moo', items: [{url: '...',description: 'moo2'},...]}

Ruan Mendes Over a year ago

This doesn't help, the case is documenting arrays of anonymous objects, not arrays of real objects

Jon Wells · Accepted Answer · 2012-08-10 08:35:25Z

1

I'd recommend checking this out. I'd probably write it something like this:

//{Object{username:<Array<Object{param1:String, param2:String,[optional_nest]:string}>>}}

edited Aug 10, 2012 at 8:35

answered Jul 30, 2012 at 9:35

Jon Wells

4,2709 gold badges42 silver badges69 bronze badges

1 Comment

Valentin Klinghammer Over a year ago

Link is dead and the above example throws "Invalid type expression" with jsdoc 3.3

Collectives™ on Stack Overflow

Questions about documenting nested array and object data with jsDoc

2 Answers 2

2 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related