How to document class properties in PHP 5 with phpDocumentor

Question

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!

Billy ONeal · Accepted Answer · 2010-02-03 19:31:40Z

55

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

answered Feb 3, 2010 at 19:31

Billy ONeal

107k61 gold badges329 silver badges566 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Pascal MARTIN · Accepted Answer · 2010-02-03 19:38:01Z

19

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.

edited Feb 3, 2010 at 19:38

answered Feb 3, 2010 at 19:32

Pascal MARTIN

402k82 gold badges665 silver badges666 bronze badges

6 Comments

Jon L. Over a year ago

@var MyClass $foo should actually be @property MyClass $foo, based on how you used it (and in that case, @property suggests a magic var). The Zend example that you posted does show proper usage of @var

Matt Over a year ago

Thanks for the detail about @access. Thats exctly what I was looking for when I found this page.

Billy ONeal Over a year ago

+1 -- but should the name of the variable be in the comment in your first example?

Pascal MARTIN Over a year ago

the docblock that comes before a variable is the one that documents that variable ; so I would say that the variable's name is implicit (but it might be useful to check how this behaves, just to be sure)

Billy ONeal Over a year ago

Yeah.. I don't have PHPDocumentor available to test with right now; but I do point out that your second example from Zend Frameowkr doesn't have the names...

|

David · Accepted Answer · 2013-08-28 07:20:48Z

8

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:

edited Aug 28, 2013 at 7:20

answered Aug 28, 2013 at 7:15

David

4,5462 gold badges26 silver badges31 bronze badges

2 Comments

Daniel W. Over a year ago

@property is used to tag magic properties. To mark class members, use @var. See manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/…

Daniel W. Over a year ago

In your example, $foo and $bar are no magic properties, because you declared them.

techraf · Accepted Answer · 2016-03-24 06:36:48Z

0

/**
 * docstring
 */
private $foo;

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

edited Mar 24, 2016 at 6:36

techraf

69.3k30 gold badges211 silver badges215 bronze badges

answered Mar 24, 2016 at 5:56

Alexander C

4,0752 gold badges26 silver badges42 bronze badges

Collectives™ on Stack Overflow

How to document class properties in PHP 5 with phpDocumentor

4 Answers 4

Comments

6 Comments

2 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

Comments

6 Comments

2 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related