注释 phpdocumentor2 的 if 语句答案

【问题标题】：Commenting if statements for phpdocumentor2注释 phpdocumentor2 的 if 语句
【发布时间】：2012-08-29 10:32:37
【问题描述】：

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

例子：

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

显然我不想添加 3 个 cmets，并且文档应该真正从逻辑上解释 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);
}

有什么想法吗？

【问题讨论】：

标签： comments phpdoc docblox

【解决方案1】：

phpdoc2 对@ignore 行为的期望可能与 phpdoc1 不同。

在 phpdoc1 中，@ignore 标签实际上意味着“你看到下一段包含可记录元素的代码了吗？忽略那段代码”。这种行为确实允许 PandyLegend 的示例完全按照上面编写的代码+文档块工作。手册中@ignore 的示例用法实际上也符合 PandyLegend 的用例 (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html)。

从我从使用 PandyLegend 的示例中看到的 phpdoc2 的行为来看，我认为 phpdoc2 正在考虑“您在下一段代码中看到了可记录的元素？记录它的名称，并在整个文档集中完全忽略该元素”。

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

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

【讨论】：