Come dichiarare parametri illimitati in DocBlock?

Question

Diciamo che ho una funzione (ovviamente un esempio banale):

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

Ora so che potrei modificare questo per essere

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

ma con alcune funzioni che non è un'opzione. Quindi, come documenteresti la prima versione della funzione con un docBlock in modo che un IDE possa interpretare che può ricevere parametri illimitati?

ho visto alcuni metodi che utilizzano:

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

Che in un IDE sembra

Ma che si sente come un hack per me, c'è modo di farlo solo con docBlock?

Answer 1

In php il concetto di valist o elenco di "argomenti opzionali" non esiste.

la variabile $_ conterrà solo, qui la terza stringa che date. L'unico modo per consentire un array o una stringa è quello di testare il primo argomento 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()); 
    } 
} 

Ora che ha gestito il comportamento desiderato, è necessario documentarlo. In PHP, poiché l'overloading non è consentito, una convenzione deve usare "mixed" come tipo se si desidera fornire più tipi.

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

Inoltre, secondo phpdocumentor documentation è possibile dichiarare una sorta di valist con

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

Answer 2

[AGGIORNATO 2015/01/08]

vecchio modo di fare questo in PHPDoc era:

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

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

Tuttavia, questo non è più supportato. A partire da PHP 5.6 Il metodo Variadic I parametri fanno parte del linguaggio PHP, e PHPDoc è stato aggiornato per riflettere questo a partire da PHPDoc 2.4 se ricordo correttamente. Questo è anche in PhpStorm IDE di EAP 139.659 (dovrebbe essere in 8.0.2 e versioni successive). Non sono sicuro sull'implementazione di altri IDE.

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

In ogni caso, sintassi corretta per DocBlocks vanno in avanti per i parametri variadic è:

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

Answer 3

Come Variadics sono implementati in PHP 5.6 PHPDocumentor dovrebbe sostenere la seguente sintassi di version 2.4.

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

Questo dovrebbe essere il modo corretto per descrivere tale firma. Questo sarà likely essere incluso in PSR-5.Una volta accettato, l'IDE dovrebbe seguire per supportare questa raccomandazione "ufficiale".

Tuttavia, nel frattempo alcuni IDE hanno un migliorato comprensione di ciò che considerano corretto. Colpisci con forza il fornitore IDE per supportare la sintassi PHP ufficiale supportata a partire da 5.6 o utilizzare qualsiasi cosa funzioni nel frattempo.