Jak zadeklarować nieograniczoną liczbę parametrów w DocBlock?

Question

Powiedzmy Mam funkcji (oczywiście trywialny przykład):

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

Teraz wiem mogę zmodyfikować to być

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

ale z niektórych funkcji, które nie wchodzi w grę. Jak więc udokumentować pierwszą wersję funkcji za pomocą docBlock, aby IDE mogło zinterpretować, że może otrzymywać nieograniczone parametry?

Widziałem kilka metod, które używają:

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

Które w IDE wygląda

jednak, że czuje się jak hack do mnie, to nie ma sposobu, aby to zrobić tylko z bloku dokumentacyjnym?

Answer 1

W php koncepcja valist lub lista "argumentów opcjonalnych" nie istnieje.

Zmienna $_ po prostu zawiera, tutaj trzeci ciąg, który podajesz. Jedynym sposobem, aby umożliwić tablicę lub ciąg jest przetestowanie pierwszy argument z 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()); 
    } 
} 

Teraz, gdy obsługiwane żądane zachowanie, trzeba je udokumentować. W php, ponieważ przeciążanie nie jest dozwolone, konwencją jest użycie "mixed" jako typu, jeśli chcesz dostarczyć wiele typów.

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

Ponadto, zgodnie z phpdocumentor documentation można zadeklarować rodzaj valist z

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

Answer 2

[AKTUALIZACJA 08.01.2015]

Stary sposób to zrobić w PHPDoc było:

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

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

Jednak nie jest to już obsługiwane. Od PHP 5.6 Parametry metody Variadic są częścią języka PHP, a PHPDoc zostały zaktualizowane tak, aby odzwierciedlały to jako PHPDoc 2.4, jeśli dobrze pamiętam. Jest to również w IDP PhpStorm od EAP 139.659 (powinno być w wersji 8.0.2 i wyższej). Nie jestem pewien co do implementacji innych IDE.

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

W każdym przypadku właściwa składnia bloków dokumentacji będzie dla parametrów o zmiennej liczbie argumentów przodu jest:

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

Answer 3

Jak Variadics są wdrażane w PHP 5.6 PhpDocumentor powinny wspierać następującą składnię jak z version 2.4.

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

Powinien to być właściwy sposób opisu takiego podpisu. To będzie likely zawarte w PSR-5.Po zaakceptowaniu tego, "oficjalna" rekomendacja powinna być zgodna z IDE.

Jednak w międzyczasie niektóre IDE mają ulepszone zrozumienie tego, co uważają za poprawne. Trafiaj mocno na dostawcę IDE, aby obsługiwał oficjalną składnię PHP obsługiwaną od wersji 5.6 lub użyj tego, co działa w międzyczasie.