How to use PHPdoc in Eclipse

We are currently in the beginning of a new project, and would like to (for once) comment as much as possible from the start to help future development.

I have tried to find out what best practices are of using phpDoc in Eclipse, but with pretty slim results.

Can you share your best practices and tricks of using phpDoc to comment stuff in Eclipse?

Solution

There is no "real standard" about what should be commented and how, but some tags are used by pretty much anyone who comments his code.

For instance, I generally use at least :

a short descriptions
optionnally, a long description
@param type name description : for the parameters of functions/methods
@returns type : for the return value of functions/methods
@throws ExceptionType : if the functions/methods throws an Exception under some circumstances
@see ... : when I want to make a reference to either another file, or an URL that gives more informations
depending of the structure of the project, I can also use @package and @subpackage
Another one that's nice when you have magic properties in a class (they cannot be seen by your IDE, as they are written in the code) is @property type $name : it allows Eclipse PDT to do auto-completion, even on magic properties -- Doctrine uses this, for instance.

Most of those are used by Eclipse PDT to help you when coding (especially @param) ; but feel free to add some that are not used by Eclipse PDT : if you generate the documentation from your code, it can always be useful ;-)

The best advice I can give you would be to take a look at the source-code of some big applications and/or frameworks (Zend Framework, Doctrine, ...), to see how their code is commented -- chances are they are using something that's well accepted.

For instance, if you take a look at Zend Framework code, you can find stuff like this for a class :

/**
 * @package    Zend_Cache
 * @subpackage Zend_Cache_Backend
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface

And like this for a method :

/**
 * Test if a cache is available for the given id and (if yes) return it (false else)
 *
 * WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend
 *
 * @param  string  $id                     cache id
 * @param  boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
 * @return string cached datas (or false)
 */
public function load($id, $doNotTestCacheValidity = false)

Anyway, the most important thing is to be consistent : every member of your team should comment the same way, follow the same conventions.