How to document a argument list with a variable length with known parameter types?

Question

Related: Correct way to document open-ended argument functions in JSDoc

I've a function that accepts multiple arrays by accessing the arguments variable:

/**
 * @param options An object containing options
 * @param [options.bind] blablabla (optional)
 */
function modify_function (options) {
    for (var i=1; i<arguments.length; i++) {
        // ...
    }
}

Now, I know that each argument besides options is an array containing values that are worth documenting:

[search_term, replacement, options]

I'm not considering putting the (lengthy) description in the variable parameter line.

@param {...} An array with search terms, replacements and its options; index 0: the search term within the function; 1: the replacement text; 2: optional options (catch_errors: catches errors and log it, escape: escape dollars in the replacement text, pos: "L" for placing the replacement before the search term, "R" for placing it after) Not a readable solution and the type is not visible.

Is there a way to document the types and values of a variable parameter?

@param {...[]} An array with search terms, replacements and its options
@param {...[0]} The search term within the function
@param {...[1]} The replacement text 
@param {...[2]} An optional object with obtions for the replacement
@param {...[2].catch_errors} catches errors and log it
@param {...[2].escape} etc...

The above looks ugly, but it should give you an idea of what I'm trying to achieve:

document the type of a variable parameter (in this case an Array)
document the values of this array
document the properties of an object inside this array

For laziness, I've used an array instead of a object. Other suggestions are always welcome.

I think the indexed *0, 1, ... k* is not a good way. Use letters or letters' sequences instead. — sergzach, Jul 27 '11 at 14:23
@sergzach: an array is indexed by numbers, not letters. I think the answer is that I should be less lazy. — Lekensteyn, Jul 27 '11 at 17:36

score 5 · Accepted Answer · answered May 07 '12 at 19:53

Your function is not truly variable arguments, you should just change its signature to what foundrama suggested. Except that JSDoc has syntax a little better than foundrama suggested

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} opts (optional) An object containing the replacement options
 * @param {Function} opts.catch_errors Description text
 * @param {Event} opts.catch_errors.e The name of the first parameter 
 *         passed to catch_errors
 * @param {Type} opts.escape Description of options
 */

And you'd call it like

modify_text('search', 'replacement', {
    catch_errors: function(e) {

    },
    escape: 'someEscape'

});

If you really do have a case for varargs style, it should be a variable of the same type that can be passed at the end of the parameter list, I document it like the following, though it's not a JSDoc standard, it's what Google uses with their documentation

/**
 * Sums its parameters
 * @param {...number} var_args Numbers to be added together
 * @return number
 */
function sum(/* num, num, ... */) { 
    var sum = 0;
    for (var i =0; i < arguments.length; i++) {
      sum += arguments[i];
    }
    return sum;
}

score 2 · Answer 2 · answered Aug 26 '11 at 12:15

Unless you are restricted by some other API, then the first thing I would suggest would be: don't use an array for anything except a data collection that you intend to iterate over.

Probably the best approach here would be to re-factor the function such that it takes three parameters or else some kind of param object. For example:

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} replacementOpts (optional) An object containing the replacement
 * options; optional values in the object include:<ul>
   <li>catch_errors {Type} description text...</li>
   <li>escape {Type} description text...</li></ul>
 */

I strongly recommend against using the array (again: "unless you're bounded by some API outside of your control) as it will prove both brittle and ultimately a little confusing.

How to document a argument list with a variable length with known parameter types?

2 Answers2