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.