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
}

Answer 1

Try:

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

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

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

Answer 2

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

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

This art of documentation is more maintainable and provable .

Extensive JSDoc s 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.