Как объявить неограниченные параметры в DocBlock?

Скажем, у меня есть функция (очевидно, тривиальный пример):

public function dot(){
    return implode('.', func_get_args());
}

Теперь я знаю, что могу изменить это, чтобы быть

public function dot(array $items){
    return implode('.', $array);
}

но с некоторыми функциями, которые не являются опцией. Итак, как бы вы задокументировали первую версию функции с помощью docBlock, чтобы среда IDI могла интерпретировать ее возможность получать неограниченные параметры?

Я видел несколько методов, которые используют:

/**
 * Joins one or more strings together with a . (dot)
 * @param string $string1
 * @param string $string2
 * @param string $_ [optional]
 * @return string
 */
public function dot($string1, $string2, $_ = null) {
    return implode('.', func_get_args());
}

Что в среде IDE выглядит как

Но для меня это похоже на взлом, нет ли способа сделать это только с docBlock?

Ответы

Ответ 1

[ОБНОВЛЕНО 2015-01-08]

Старый способ сделать это в PHPDoc:

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

/**
 * @param int $param,...
 **/

Однако это больше не поддерживается. Начиная с PHP 5.6 Variadic Method Параметры являются частью языка PHP, и PHPDoc был обновлен, чтобы отразить это как PHPDoc 2.4, если я правильно помню. Это также в среде PhpStorm IDE с EAP 139.659 (должно быть в 8.0.2 и выше). Не уверены в реализации других IDE.

https://youtrack.jetbrains.com/issue/WI-20157

В любом случае правильный синтаксис для DocBlocks, идущий вперед для переменных параметров:

/**
 * @param int ...$param
 **/

Ответ 2

Как Variadics реализованы в PHP 5.6 PHPDocumentor должен поддерживать следующий синтаксис: версия 2.4.

/**
 * @param Type ...$value
 * Note: PHP 5.6+ syntax equal to func_get_args()
 */
public function abc(Type ...$value) {}

Это должен быть правильный способ описать такую подпись. Это вероятно будет включено в PSR-5. Как только это будет принято, IDE следует придерживаться, чтобы поддержать эту "официальную" рекомендацию.

Однако, в то время как некоторые IDE улучшают понимание того, что они считают правильным. Усильте поставщика IDE для поддержки официального синтаксиса PHP, который поддерживается с 5,6 или использует все, что работает в то же время.

Ответ 3

В php понятие valist или список "необязательных аргументов" не существует.

переменная $_ будет содержать только ту третью строку, которую вы даете. Единственный способ разрешить массив ИЛИ строку - проверить первый аргумент с помощью is_array()

public function dot($arg1){
   if(is_array($arg1)){
       return implode('.',$arg1);
   }
   else if $arg1 instanceof \Traversable){
       return implode('.',iterator_to_array($arg1));
   }
   else{
       return implode('.',func_get_args());
   }
}

Теперь, когда вы обработали нужное поведение, вы должны его документировать. В php, поскольку перегрузка не разрешена, соглашение должно использовать "смешанный" как тип, если вы хотите предоставить несколько типов.

/**
*@param mixed $arg1 an array, iterator that will be joined OR first string of the list
*@return string a string with all strings of the list joined with a point
*@example dot("1","2","3"); returns 1.2.3 dot(array(1,2,3)); returns 1.2.3
*/

Кроме того, согласно документации phpdocumentor, вы можете объявить своего рода valist с

/**
*@param string ... list of strings
*/