Sintassi di chiusura in PHPDoc

Question

Non riesco a trovare alcuna documentazione sul tipo di chiusura in PHPDoc. Quindi la mia domanda è: come definire il parametro dei parametri inviati alla chiusura e il suo valore di ritorno?

Esempio:

Come faccio a descrivere che il "callback" otterrà un "myCustomClass", un numero e una stringa, e restituire un "MyOtherCustomClass"?

/** 
* @param MyCustomClass $cls 
* @param Closure  $callback this isn't really explaining what this is 
* 
* @return MyOtherCustomClass 
*/ 
function changer($cls, $callback){ 

    return $callback($cls, 2, "a string"); 
} 

changer($aCustomeClass, function($cls, $int, $string){ 
    return new MyOtherCustomClass($cls, $int, $string); 
}) 

O se è possibile?

Answer 1

@param callable $callback è effettivamente la sintassi da utilizzare per quella parte. Non stai limitando questo parametro all'essere una chiusura in sé ... qualsiasi callable che viene passato ad esso sarà accettato in quella implementazione. Callable è un "tipo PHP" legale, quindi phpDocumentor lo accetta come tipo valido.

Nel codice esempio, c'è in realtà non una ragione di presumere che il metodo restituisce un changer()MyOtherCustomClass(), dal momento che è puramente dettata da come si scrive la chiusura più avanti nell'uso changer(). Nella migliore delle ipotesi, si potrebbe denotare in un commento al l'utilizzo changer() che questo particolare uso di changer() rendimenti MyOtherCustomClass, perché è che l'attuazione di utilizzo, non il changer() realizzazione in sé, che restituisce quel tipo specifico di oggetto.

Per quanto riguarda la documentazione degli argomenti che il callable passato è "richiesto" per accettare, suppongo che dovresti farlo nella parte descrittiva del tag param. Non esiste una sintassi per descrivere un caso del genere.

Se dovessi implementare qualcosa in questo modo, imporre un'interfaccia che tutti i chiamanti devono restituire esplicitamente, quindi potrei scrivere che l'interfaccia changer() restituisce tale interfaccia. Ovviamente, questo significa che il tuo MyOtherCustomClass deve implementare quell'interfaccia, ma comunque, a me sembra che sia l'unico modo per avvicinarsi a "imporre" un tipo di ritorno da changer().