CODEWITHSUNDEEP
phpclassphpdoc
AlexV
AlexV

Reputation: 23088

How to document class properties in PHP 5 with phpDocumentor

Take in consideration the following PHP 5 class:

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

How in phpDocumentor will I document the $foo property? I'm not even sure it need to be documented but I would like to know how if if needs to...

I know how to document SetFoo() and GetFoo(), I'm just not sure about the private property (variable?).

Thanks!

Upvotes: 37

Views: 32872

Answers (4)

Alexander C
Alexander C

Reputation: 4017

/**
 * docstring
 */
private $foo;

Important note: there should be two asterisks. Not one.

Upvotes: 0

David
David

Reputation: 4516

In the case you use a __get and __set magic methods you can use @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(){
         ...
     }
 }

Links with more info:

Upvotes: 7

Pascal MARTIN
Pascal MARTIN

Reputation: 400932

I would generally use at least the @var tag, to indicate the type of variable this is.

For instance :

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


This is exactly what's done by Zend Framework, for instance ; see Zend_Layout (quoting) : 

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


Note : the @access tag was useful with PHP 4 (when there were no public/protected/private), but I never use it when I document code written in PHP 5 : the code, using the visibility keywords is self-documenting.

Upvotes: 19

Billy ONeal
Billy ONeal

Reputation: 106530

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

Upvotes: 55

Related Questions