注释phpdocumentor2的if语句

Question

我正在使用PHPDocumentor2记录一个PHP项目。具有讽刺意味的是，PHPDoc的文档并不太详细。我完全理解如何注释文件、类、函数和变量，但是如果在if语句中定义了一个变量或常量，我应该如何注释它？

示例：

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

显然，我不想添加3个注释，文档应该真正解释if语句，所以从逻辑上讲，定义应该放在if语句的开始之前--这在代码视图中是最美观的--但是docBlock必须在“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的示例与上面编写的code+docblocks完全相同。手册中@ignore的示例用法实际上也符合PandyLegend的用例(http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html)。

从我在使用PandyLegend的例子中看到的phpdoc2的行为来看，我认为phpdoc2在想“你在下一段代码中看到了documentable元素吗?记录下它的名称，然后在整个文档集中完全忽略这个元素”。

我的猜测是，这个问题实际上只是一种不同的解释，而不是一个bug。

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