How to write a Doxygen comment for variadic function, i.e., a function with undefined number of arguments?

Question

I am trying to write a doxygen block comment for a function with unlimited number of parameters, then I couldn't find a right tag for it. Supplied parameters should all be strings, and they will be concatenated in the function to form a new string.

What is the right use of doxygen tags?

Just /write/ it. Documentation is just that, it's not supposed to be executable or formal, imho — sehe, Apr 05 '11 at 09:14
There's a new feature in PHP 5.6, which will make this way easier. http://philsturgeon.uk/blog/2013/08/potential-variadic-function-syntax-for-php-56 — aross, Aug 07 '14 at 10:13

score 12 · Accepted Answer · edited Apr 05 '12 at 12:14

12

A pattern I see frequently in phpdoc (the format of which doxygen understands) is:

/** 
 * Shortdesc.
 * Longdesc.  Longdesc.  Longdesc.  Longdesc.  
 * @param mixed $something Description
 * @param mixed ... Description
 */
    function foo() { ... }

Yes, literally ... as the variable name.

edited Apr 05 '12 at 12:14

Gordon

312,688
75
539
559

answered Apr 05 '11 at 21:04

Charles

50,943
13
104
142

3

The `...` is incorrect syntax! The correct syntax is `$paramname,...` – Fred Mar 08 '14 at 15:13
3

@Fred, at the time I wrote this **three years ago**, it was correct. – Charles Mar 09 '14 at 07:59

score 5 · Answer 2 · answered Mar 08 '14 at 15:12

5

Actually, the syntax on the phpDocumentor is $paramname,...

/**
 * Builds a file path with the appropriate directory separator.
 * @param string $segments,... unlimited number of path segments
 * @return string Path
 */
function file_build_path(...$segments) {
    return join(DIRECTORY_SEPARATOR, $segments);
}

answered Mar 08 '14 at 15:12

Fred

12,086
7
60
83

It would be nice to have an authoritative link to support your answer! – BenMorel Sep 10 '14 at 20:41
You're right @Benjamin http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.param.pkg.html – Fred Sep 11 '14 at 21:27

How to write a Doxygen comment for variadic function, i.e., a function with undefined number of arguments?

2 Answers2