PHPDoc: documentazione di una function con un numero variabile di argomenti

Qual è il metodo consigliato per documentare un metodo di class che accetta un numero variabile di argomenti?

Forse qualcosa del genere?

<?php class Foo { /** * Calculates the sum of all the arguments. * * @param mixed [$arg1, $arg2, ...] * * @return float the calculated sum */ public static function sum() { return arrays_sum(func_get_args()); } } 

Nota: come regola generale, immagino che questo tipo di cosa dovrebbe essere evitato ladwhere ansible. Detto questo, sarebbe bello documentare ancora i pochi casi rimanenti in cui non può essere evitato.

 /** * @param mixed $numbers,... Description */ Public function sum ($numbers) 

Nel metodo, i numbers $ non saranno usati.

Se usi un numero variabile di argomenti e usi anche PHP >= 5.6 allora sei in grado di usare le funzioni variadiche (permettendo il numero variabile di argomenti) che è ancora conforms alla syntax PHPDoc ,... già menzionata e PHPStorm interpnetworkingrà correttamente i documenti anche. L'uso delle funzioni variad elimina la necessità di func_get_args() per acquisire argomenti in un arrays.

 /** * @param mixed $args,... Explainatorium! */ function variadiculous(...$args) { // NOTE: $args === func_get_args() foreach ( $args as $arg ) { /* do work */ } } 

PHPStorm genererà automaticamente i documenti come @param arrays $args perché tecnicamente quando all'interno della function variadiculous is_arrays($args) è vero. Lo cambio per leggere @param mixed $args,... come sopra e quando uso il tasto di scelta rapida per visualizzare una firma di function da qualche altra parte nel mio codice PHPStorm visualizza variadiculous($args : ...arrays|mixed) – I consiglia di utilizzare questo metodo se usi PHP> = 5.6

Nel caso della ... syntax , PHPStorm 2017.1 utilizza:

 /** * @param Type[] ...$values One or more values. */ public function func(Type ...$values) { // ... }