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

Posted 2023-02-22

【中文标题】如何使用 phpDocumentor 在 PHP 5 中记录类属性

【英文标题】：How to document class properties in PHP 5 with phpDocumentor

【发布时间】：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()，我只是不确定私有属性（变量？）。

谢谢！

【参考方案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()
         ...
     
 

更多信息的链接：

http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/property.html http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.property.pkg.html

【讨论】：

@property 用于标记魔法属性。要标记班级成员，请使用@var。见manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/…

在您的示例中，$foo 和 $bar 不是魔法属性，因为您声明了它们。

【参考方案4】：

/**
 * docstring
 */
private $foo;

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