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语句，所以逻辑上docBlock应该在if语句的开头之前去 - 这在代码视图中最美观 - 但是docBlock必须紧接在“define”之前。我可以把它放在第一个之前，但这看起来很奇怪。

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的示例完全像上面编写的代码+ docblock一样工作。该手册的@ignore示例用法实际上也与PandyLegend的用例相匹配（http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html）。

从phpdoc2的行为来看，我从使用PandyLegend的例子看，我认为phpdoc2正在考虑“你在下一段代码中看到了可记录元素？记录它的名字，并在整套文档中完全忽略该元素”。< / p>

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

（https://github.com/phpDocumentor/phpDocumentor2/issues/583）

评论phpdocumentor2的if语句

1 个答案: