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!

score 54 · Accepted Answer · answered Feb 03 '10 at 19:31

54

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

answered Feb 03 '10 at 19:31

Billy ONeal

104,103
58
317
552

Pascal MARTIN · Answer 2 · 2010-02-03T19:38:01.083

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 03 '10 at 19:38

answered Feb 03 '10 at 19:32

Pascal MARTIN

395,085
80
655
663

@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 – Jon L. Jul 13 '11 at 16:45
Thanks for the detail about @access. Thats exctly what I was looking for when I found this page. – Matt Jun 16 '12 at 21:21
+1 -- but should the name of the variable be in the comment in your first example? – Billy ONeal Oct 17 '12 at 16:21
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)* – Pascal MARTIN Oct 17 '12 at 16:37
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... – Billy ONeal Oct 17 '12 at 17:58
I don't use phpDocumentor at work, but I always put docblocks to help PHPStorm with auto-completion -- and I don't always put the variable name either. – Pascal MARTIN Oct 17 '12 at 18:32

David · Answer 3 · 2013-08-28T07:20:48.543

7

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 '13 at 07:20

answered Aug 28 '13 at 07:15

David

4,336
2
23
31

4

`@property` is used to tag magic properties. To mark class members, use `@var`. See http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.property.pkg.html – Daniel W. Dec 11 '14 at 16:07
In your example, `$foo` and `$bar` are no magic properties, because you declared them. – Daniel W. Dec 11 '14 at 16:09

score 0 · Answer 4 · edited Mar 24 '16 at 06:36

0

/**
 * docstring
 */
private $foo;

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

edited Mar 24 '16 at 06:36

techraf

64,883
27
193
198

answered Mar 24 '16 at 05:56

Alexander C

3,597
1
23
39

How to document class properties in PHP 5 with phpDocumentor

4 Answers4