How to document unlimited argument parameters?

Question

In PHP you can have a function take an infinite number of arguments like

 /**
 * Do abc...
 *
 * @since 1.0
 * @param mixed $arg1 Arg description
 * @return string Results
 */
function abc($arg1 = null){
 $args = func_get_args();
 // do smth with $args
}

How should I illustrate this in my DocBlock ?

Answer 1

phpdoc.org manual example:

/**
 * @param mixed $varname,... unlimited OPTIONAL number of additional variables [...]
 */

You may document parameters listed or any optional paramters that will be parsed by standard PHP functions func_num_args()/get_func_arg(). Recommended name format for parameters listed with func_get_arg() is:

• $paramname if there is only one parameter
• $paramname,... if the number of parameters is unlimited

phpDocumentor will display the optional description unmodified.

Note that the $paramname,... will be shown in the output docs in both the parameter listing AND the function signature. If you are not indicating in the actual code that the parameter is optional (via "$paramname = 'a default value'"), then you should mention in the parameter's description that the parameter is optional.