Как PHPDoc анонимная функция при передаче в качестве аргумента?

Question

Как мне документировать анонимную функцию, когда она передается в качестве аргумента? Например:

// Call my_function(), passing 2 arguments.
my_function( 'foo', function() {
    // Body of the anon function I'd like to document.
} );

Заранее спасибо.

Answer 1

Чтобы задокументировать, что функция принимает Закрытие, я бы предложил вызвать:

/**
 * Do something.
 * @param callable $code
 */
function foo(callable $code) {
}

Что касается комментария, PHPDoc использует DocBlocks, которые движок PHP Tokenizer распознает только выше формальные определения. Таким образом, PHPDoc не увидит этого:

/**
 * My closure.  PHPDoc will *not* parse this, because it's not a formal definition.
 * @param string $name
 */
$closure = function ($name) { return $name; };

Answer 2

Это сработало для меня до сих пор:

interface CustomCallback
{
    /**
     * @return string
     */
    public function __invoke();
}

/**
 * @param string $a
 * @param CustomCallback $b
 * @return void
 */
my_function($a, $b) {

}

Это говорит нам о том, что второй параметр my_function ожидает что-то, что реализует CustomCallback интерфейс. Посмотрев в интерфейс CustomCallback, мы увидим, что он вызывается из-за метода __invoke. Затем, просмотрев документацию по методу __invoke, мы увидим, какие параметры он ожидает и тип возвращаемого значения.