autocomplete - generate - phpstorm comment shortcut

¿Cómo declarar parámetros ilimitados/variados en DocBlock?

Question

Digamos que tengo una función (obviamente un ejemplo trivial):

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

Ahora sé que podría modificar esto para ser

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

Pero con algunas funciones eso no es una opción. Entonces, ¿cómo documentaría la primera versión de la función con un docBlock para que un IDE pueda interpretar que puede recibir parámetros ilimitados?

He visto algunos métodos que utilizan:

/**
 * 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());
}

Que en un IDE parece

Pero eso me parece un truco, ¿no hay manera de hacerlo solo con docBlock?

Answer 1

Como los Variadics se implementan en PHP 5.6, PHPDocumentor debe admitir la siguiente sintaxis a partir de la versión 2.4 .

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

Esta debería ser la manera correcta de describir tal firma. Esto likely será incluido en PSR-5 . Una vez que se acepte, IDE debe seguir para apoyar esta recomendación "oficial".

Sin embargo, mientras tanto, algunos IDE tienen una mejor comprensión de lo que consideran correcto. Golpee con fuerza al proveedor de IDE para admitir la sintaxis oficial de PHP que se admite a partir de 5.6 o use lo que funcione mientras tanto.

Answer 2

En php no existe el concepto de valist o lista de "argumentos opcionales".

La variable $_ solo contendrá, aquí la tercera cadena que das. La única forma de permitir una matriz O una cadena es probar el primer argumento con 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());
   }
}

Ahora que manejó el comportamiento que desea, debe documentarlo. En PHP, como la sobrecarga no está permitida, una convención es usar "mixto" como un tipo si desea proporcionar varios tipos.

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

Además, según la http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html , puede declarar una especie de lista con

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

Answer 3

[ACTUALIZADO 2015-01-08]

La vieja forma de hacer esto en PHPDoc era:

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

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

Sin embargo, esto ya no es compatible. A partir de PHP 5.6, los parámetros del método Variadic son parte del lenguaje PHP, y los PHPDoc se han actualizado para reflejar esto a partir de PHPDoc 2.4 si recuerdo correctamente. Esto también está en el IDE de PhpStorm a partir de EAP 139.659 (debería estar en 8.0.2 y superior). No estoy seguro acerca de la implementación de otros IDEs.

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

En cualquier caso, la sintaxis adecuada para los DocBlocks que avanzan para los parámetros variadic es:

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