Składnia zamknięcia w PHPDoc

Question

Nie mogę znaleźć żadnej dokumentacji dotyczącej typu zamknięcia w PHPDoc. Moje pytanie brzmi: jak zdefiniować parametr parametrów wysyłanych do zamknięcia i jego wartości zwracanej?

Przykład:

Jak mogę opisać, że "callback" dostanie "MyCustomClass", numer i ciąg i powrócić do "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); 
}) 

A może w ogóle jest to możliwe?

Answer 1

@param callable $callback jest rzeczywiście składnią do zastosowania w tej części. Nie ograniczasz tego parametru do samego zamknięcia ... każda przekazywana do niego wartość jest akceptowana w tej implementacji. Callable jest legalnym "typem PHP", więc phpDocumentor akceptuje go jako prawidłowy typ.

W przykładzie kodu, tam faktycznie nie powód, aby przypuszczać, że metoda changer() zwraca MyOtherCustomClass(), ponieważ jest wyłącznie podyktowana jak piszesz zamknięcie później w używaniu changer(). W najlepszym wypadku, można oznaczać w komentarzu na wykorzystanie changer() że tym konkretnym zastosowaniem changer()MyOtherCustomClass zwrotów, ponieważ jest to, że realizacja Usage, a nie realizacja sama changer(), która zwraca danego typu obiektu.

Jeśli chodzi o dokumentowanie argumentów, że przekazana liczba wywołań jest "wymagana" do zaakceptowania, to przypuszczam, że musiałbyś to zrobić w opisie znacznika param. Nie ma żadnej składni, aby opisać taki przypadek.

Gdybym miał coś zaimplementować w ten sposób, narzucałbym interfejs, który wszystkie kalki muszą jawnie zwracać, a więc mógłbym napisać, że ten interfejs zwraca. Oczywiście oznacza to, że twój MyOtherCustomClass musi implementować ten interfejs, ale nadal wydaje mi się, że jest to jedyny sposób zbliżenia się do "egzekwowania" typu zwrotu z changer().