Правильный способ настройки и документирования неограниченных параметров для работы? - PullRequest
Новая
       14

Правильный способ настройки и документирования неограниченных параметров для работы?

0 голосов
/ 07 сентября 2011

Справочная информация: Я создаю метод addAll, который добавляет все значения, переданные методу, в мой класс. Вот о чем я думал: 

public function addAll() {
    if(func_num_args()===0) {
        throw new BadMethodCallException(get_class($this).'::addAll() must have arguments.');
    }

    $args = func_get_args();

    foreach($args as &$arg) {
        $this->add($arg);
    }
}

И это прекрасно работает. Затем я документировал это с помощью phpDocumentor: 

/**
 * @param mixed ... All of the values to add.
 */

. , , но у меня нет названия для моего @param, потому что, честно говоря, его не существует.

Вопрос: Как мне сконструировать и определить что-то подобное?

Поскольку я хочу, чтобы в него было передано хотя бы одно значение, я пришел к этому, но не уверен: 

/**
 * @param mixed $value,... All of the values to add.
 */
public function addAll($value) {
    $args = func_get_args();

    foreach($args as &$arg) {
        $this->add($arg);
    }
}

Кажется, это неправильно, потому что $value никогда не используется напрямую. , .

Кроме того, у меня уже есть add, который добавляет один, так разве addAll семантически не должен требовать хотя бы двух параметров? Что бы вы порекомендовали для определения и документирования этого?

1 Ответ

0 голосов
/ 01 октября 2011

Ответ: используйте тег @example.

Я также изменил свои настройки, и, похоже, это лучший способ использовать то, что предлагает PHP, без ущерба для удобства использования: 

/**
 * @param mixed $values Either an array of values to add, or multiple values
 * @example
 * 
 * $object->add('1');
 * $object->add('1','2');
 * $object->add(array('1','2'));
 * 
 * @return type 
 */
public function add($values=null) {
    if (is_array($values)) {
        return $this->addAll($values);
    } else {
        return $this->addAll(func_get_args());
    }
}
...