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:
For laziness, I've used an array instead of a object. Other suggestions are always welcome.
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;
}