使用 phpDocumentor 记录类常量组答案

【问题标题】：Documenting groups of class constants with phpDocumentor使用 phpDocumentor 记录类常量组
【发布时间】：2011-11-11 11:55:00
【问题描述】：

假设我有一个方法，它有一个参数，其有效值被声明为类常量（想想PGSQL_ASSOC/PGSQL_NUM/PGSQL_BOTH）。还有另一种方法，具有类似的参数，使用另一组类常量。有没有办法向 phpDocumentor 描述每组常量属于一组逻辑选项？将它们分组记录并能够在方法文档中引用特定组将很有用。使用 docblock 模板并没有减少它，因为模板的简短描述被忽略（添加无用的混乱），而模板的长描述被附加到特定于常量的描述，导致一种向后的措辞（例如“BAR_MODE_1 确实这个和那个。Foo::bar() 的操作模式”，而不是“Foo::bar() 的操作模式：BAR_MODE_1 做这个和那个。”）。

例子：

class Foo {

    // this group of constants are valid modes for the bar() method
    const BAR_MODE_1 = 1;
    const BAR_MODE_2 = 2;
    const BAR_MODE_3 = 3;

    /**
     * @param int see Foo::BAR_MODE_* constants
     */
    public function bar($mode) { ... }

    // this group of constants are valid modes for the baz() method
    const BAZ_MODE_1 = 1;
    const BAZ_MODE_2 = 2;
    const BAZ_MODE_3 = 3;

    /**
     * @param int see Foo::BAZ_MODE_* constants
     */
    public function baz($mode) { ... }

}

【问题讨论】：

标签： php phpdoc

【解决方案1】：

另一种风格可能是使用 PHPDocumentor DocBlock 模板

/**#@+
* This comment applies to each in the block
*
* @var varType 
*/
protected $_var1 = 1;
protected $_var2 = 2;
/**#@-*/

见：http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock

【讨论】：

我实际上在我的问题中提到了 docblock 模板，以及为什么它在这种情况下没有用。
是的，我错过了。然而，当我再次用谷歌搜索如何做 DocBlock 模板时，让这段代码在这里很有用；）

【解决方案2】：

我首先想到的是@see - 标签，它显示一个元素文档的链接。

/**
 * @param int 
 * @see Foo::BAR_MODE_* constants
 */
public function bar($mode) { ... }

更多详情请见here in the manual。

【讨论】：

该指令仅在文档中呈现文本行。我什至看不到如何使其成为常量部分的链接，在我的情况下，相关常量甚至没有定义在与方法相同的类中，而是在父类中。
实际上，@see Foo::BAR_MODE_1 产生了一个链接，但隐藏了与其余 BAR_MODE_* 常量的关系