Комментирование операторов if для phpdocumentor2

Question

Я нахожусь в процессе документирования проекта PHP с использованием PHPDocumentor2. По иронии судьбы документация PHPDoc не слишком детализирована. Я полностью понимаю, как комментировать файлы, классы, функции и переменные, однако, если переменная или константа определяется в операторе if, как мне это комментировать?

Пример:

if ($foo==$bar) {
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

Ясно, что я не хочу добавлять 3 комментария, и документация должна действительно объяснять оператор if так логично, что docBlock должен идти перед началом оператора if - это было бы наиболее эстетично в представлении кода - но docBlock должен быть на линии непосредственно перед "определить". Я могу поставить это перед первым, но это выглядит странно.

if ($foo==$bar) {
    /**
     * FOOBAR Definition.
     *
     * Value of FOOBAR. Yada yada.
     * @var int
     */
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

Есть идеи?

Answer 1

Вполне возможно, что ожидание phpdoc2 поведения @ignore отличается от ожидания phpdoc1.

В phpdoc1 тег @ignore фактически означает "вы видите следующий фрагмент кода, в котором есть документируемый элемент? Просто игнорируйте этот фрагмент кода". Такое поведение действительно позволяло примеру PandyLegend работать точно так же, как код + докблоки написаны выше. Пример использования руководства для @ignore фактически совпадает с примером использования PandyLegend (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html).

Судя по поведению phpdoc2, которое я вижу на примере PandyLegend, я думаю, что phpdoc2 думает: "Вы видите документируемый элемент в следующем фрагменте кода? Запишите его имя и полностью проигнорируйте этот элемент во всем этом наборе документации".

Я думаю, что эта проблема на самом деле просто другая интерпретация, а не ошибка.

(Https://github.com/phpDocumentor/phpDocumentor2/issues/583)