Синтаксис закрытия в PHPDoc

Я не могу найти документацию по типу Closure в PHPDoc. Итак, мой вопрос заключается в том, как определить параметр параметров, отправленных в закрытие и его возвращаемое значение?

Пример:

Как я могу описать, что "обратный вызов" получит "MyCustomClass", Number и String и вернет "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);
})

Или, если это вообще возможно?

Ответы

Ответ 1

@param callable $callback действительно является синтаксисом для использования для этой части. Вы не ограничиваете этот параметр тем, что являетесь самим замыканием... любой вызываемый, который передается ему, будет принят в этой реализации. Callable - это законный "тип PHP", поэтому phpDocumentor принимает его как действительный тип.

В вашем примере кода на самом деле нет оснований полагать, что ваш метод changer() возвращает MyOtherCustomClass(), поскольку это просто диктуется тем, как вы пишете закрытие позже в использовании changer(). В лучшем случае вы отметили бы в комментарии при использовании changer(), что это конкретное использование changer() возвращает MyOtherCustomClass, потому что это реализация использования, а не сама реализация changer(), которая возвращает определенный тип объект.

Что касается документирования аргументов, которые переданный вызываемый "требуется" для принятия, я полагаю, вам придется сделать это в части описания тега param. Для описания такого случая нет синтаксиса.

Если бы я должен был что-то реализовать таким образом, я бы наложил интерфейс, который вызывающие все должны явно возвращать, и поэтому я мог бы написать, что changer() возвращает этот интерфейс. Конечно, это означает, что ваш MyOtherCustomClass должен реализовать этот интерфейс, но тем не менее, мне кажется, что это единственный способ приблизиться к "принудительному" возврату типа из changer().