如何使用 phpDocumentor 在 PHP 5 中记录类属性答案

【问题标题】：How to document class properties in PHP 5 with phpDocumentor如何使用 phpDocumentor 在 PHP 5 中记录类属性
【发布时间】：2011-01-12 18:46:40
【问题描述】：

考虑以下 PHP 5 类：

class SomeClass
{
    //I want to document this property...
    private $foo;


    function __construct()
    {

    }

    public function SetFoo($value)
    {
        $this->foo = $value;
    }

    public function GetFoo()
    {
        return $this->foo;
    }
}

如何在phpDocumentor 中记录 $foo 属性？我什至不确定它是否需要记录在案，但我想知道如果需要的话……

我知道如何记录 SetFoo() 和 GetFoo()，我只是不确定私有属性（变量？）。

谢谢！

【问题讨论】：

标签： php class phpdoc

【解决方案1】：

/**
 * This is what the variable does. The var line contains the type stored in this variable.
 * @var string
 */
private $foo;

【讨论】：

【解决方案2】：

我通常会至少使用@var 标记来表明这是变量的类型。

例如：

/**
 * Some blah blah about what this is useful for
 * @var MyClass $foo
 */

例如，这正是 Zend Framework 所做的；见Zend_Layout（引用）：

class Zend_Layout
{
    /**
     * Placeholder container for layout variables
     * @var Zend_View_Helper_Placeholder_Container
     */
    protected $_container;

    /**
     * Key used to store content from 'default' named response segment
     * @var string
     */
    protected $_contentKey = 'content';

注意：@access 标签在 PHP 4 中很有用（当没有 public/protected/private），但是当我记录用 PHP 5 编写的代码时，我从不使用它：代码，使用可见性关键字是自记录的。

【讨论】：

@var MyClass $foo 实际上应该是 @property MyClass $foo，这取决于您如何使用它（在这种情况下，@property 建议使用一个神奇的 var）。您发布的 Zend 示例确实显示了 @var 的正确用法
感谢您提供有关@access 的详细信息。这正是我找到此页面时所寻找的。span>
+1 -- 但是变量的名称应该在第一个示例的注释中吗？
变量之前的文档块是记录该变量的文档块；所以我会说变量的名称是隐含的（但检查一下它的行为可能很有用，只是为了确定）
是的.. 我现在没有 PHPDocumentor 可供测试；但我确实指出，您来自 Zend Frameowkr 的第二个示例没有名称...

【解决方案3】：

如果您使用 __get 和 __set 魔术方法，您可以使用@property

/**
  * Description for the class
  * @property type $foo Description for foo
  * @property type $foo Description for bar
  */
 class SomeClass
 {
     private $foo;
     protected $bar;

     public function __get(){
         ...
     }

     public function __set(){
         ...
     }
 }

更多信息的链接：

【讨论】：

@property 用于标记魔法属性。要标记班级成员，请使用@var。见manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/…
在您的示例中，$foo 和 $bar 不是魔法属性，因为您声明了它们。

【解决方案4】：

/**
 * docstring
 */
private $foo;

重要提示：应该有两个星号。一个都没有。

【讨论】：