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

Posted by nickf on Stack Overflow See other posts from Stack Overflow or by nickf
Published on 2010-05-20T05:24:43Z Indexed on 2010/05/20 5:30 UTC
Read the original article Hit count: 329

Filed under:
|
|

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?

© Stack Overflow or respective owner

Related posts about documentation

Related posts about phpdoc