Documenting an array of objects as a parameter of callback function in JSDoc

Question

callback.rows is array of arbitrary length with a number of repeating fields.

How can I document each field (type, property, description) in JSDoc?

Is there possible to apply this method?

Or may be this solution can be accepted:

/**
* Get list of all documents
* @param {Function} callback                      Standard callback function
* @param {Error}    callback.err                  Error object if any
* @param {Array}    callback.rows                 Rows list
* @param {String}   callback.rows[0].field1       field1
*/
var myFunc = function (callback) {
   // Function body
}

I always write the parameters of the callback in the description. Who reads the docs anyways :)? — A1rPun
– A1rPun, Commented Nov 24, 2014 at 15:46

Etai · Accepted Answer · 2014-11-24 18:14:23Z

3

Try:

/**@param {string[]} callback.rows*/

Note that you can put any type there, not just string... Such as

/**@param {{field1: string}[]} callback.rows */

answered Nov 24, 2014 at 18:14

Etai

1,5031 gold badge11 silver badges15 bronze badges

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

1 Comment

hellboy Over a year ago

The second option is OK for me

hellboy · Accepted Answer · 2015-02-06 08:11:26Z

0

As I mentioned the best documentation for your code is unit tests.

In JSDoc should be only main parameters documented. I.e. callback is Function. The last 3 lines should be moved into your unit test.

This art of documentation is more maintainable and provable.

Extensive JSDocs are hard to read and maintain. Not all behavior can be documented.

Not all people can correct understand this documentation. Some people will try to change documentation on your own flavor.

answered Feb 6, 2015 at 8:11

hellboy

1,6286 gold badges23 silver badges58 bronze badges

Collectives™ on Stack Overflow

Documenting an array of objects as a parameter of callback function in JSDoc

2 Answers 2

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related