Как документировать метод доступа / мутатора в phpDoc / javaDoc? - PullRequest
Новая
       19

Как документировать метод доступа / мутатора в phpDoc / javaDoc?

0 голосов
/ 20 мая 2010

Дана функция, которая ведет себя как мутатор или метод доступа в зависимости от переданных ей аргументов, например: 

// 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

Как вы документируете это в PHPDoc или аналогичном автоматизированном редакторе документации? Первоначально я просто написал это так: 

/**
 *  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
 */

Однако, когда он запускается через phpDoc, он жалуется, потому что есть 2 возвращаемых тега, а первое описание @param $cacheName заменяется вторым.

Есть ли способ обойти это?

1 Ответ

2 голосов
/ 20 мая 2010

как вы узнали, вы не можете задокументировать 2 разных подписи одной функции. однако, что вы можете сделать - если вы используете phpDocumentor -, это документировать необязательные параметры функции и несколько возможных типов возврата : 

/**
 * 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
 */

для ясности, я бы также включил пример использования.

...