sirve - phpdocumentor tutorial

Cómo documentar propiedades de clase en PHP 5 con phpDocumentor

Question

Tome en consideración la siguiente clase de 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;
    }
}

¿Cómo en phpDocumentor documentaré la propiedad $ foo? Ni siquiera estoy seguro de que deba documentarse, pero me gustaría saber cómo, si es necesario ...

Sé cómo documentar SetFoo () y GetFoo (), simplemente no estoy seguro acerca de la propiedad privada (¿variable?).

¡Gracias!

Answer 1

En el caso de que uses métodos mágicos __get y __set, puedes usar @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(){
         ...
     }
 }

Enlaces con más información:

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

Answer 2

Generalmente usaría al menos la etiqueta @var , para indicar el tipo de variable que es.

Por ejemplo :

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

Esto es exactamente lo que hace Zend Framework, por ejemplo; ver Zend_Layout (citando) :

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'';

Nota: la etiqueta @access fue útil con PHP 4 (cuando no había public / protected / private ) , pero nunca la uso cuando documento el código escrito en PHP 5: el código, el uso de las palabras clave de visibilidad es autodocumentado.

Answer 3

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

Answer 4

/**
 * docstring
 */
private $foo;

Nota importante: debe haber dos asteriscos. Ni uno.