How to document an accessor/mutator method in phpDoc/javaDoc? - php

Question

Given a function which behaves as either a mutator or accessor depending on the arguments passed to it, like this:
// in PHP, you can pass any number of arguments to a function...
function cache($cacheName) {
$arguments = func_get_args();
if (count($arguments) >= 2) { // two arguments passed. MUTATOR.
$value = $arguments[1]; // use the second as the value
$this->cache[$cacheName] = $value; // *change* the stored value
} else { // 1 argument passed, ACCESSOR
return $this->cache[$cacheName]; // *get* the stored value
}
}
cache('foo', 'bar'); // nothing returned
cache('foo') // 'bar' returned
How do you document this in PHPDoc or a similar automated documentation creator? I had originally just written it like this:
/**
* Blah blah blah, you can use this as both a mutator and an accessor:
* As an accessor:
* #param $cacheName name of the variable to GET
* #return string the value...
*
* As a mutator:
* #param $cacheName name of the variable to SET
* #param $value the value to set
* #return void
*/
However, when this is run through phpDoc, it complains because there are 2 return tags, and the first #param $cacheName description is overwritten by the second.
Is there a way around this?

Answer 1

as you found out, you cannot document 2 different signatures of a single function. what you can do, however - if you use phpDocumentor -, is to document optional function parameters and multiple possible return types:
/**
* Blah blah blah, you can use this as both an accessor and a mutator, e.g.
* <code>cache('name') // get cache value</code>
* and
* <code>cache('name', 'value') // set new cache value</code>.
*
* #param string $cacheName name of the variable to GET|SET
* #param string $value optional new value
*
* #return string|void value of $cacheName or, in case of mutator, void
*/
for clarity, i would also include the usage example.