How to use PHPdoc in Eclipse

Question

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?

Answer 1

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.

Answer 2

At a bare minimum, I'd at least stick with what minimal phpdoc tags are automatically inserted by Eclipse based on your code.

The second minimal level I'd strive for would be to keep PhpDocumentor itself happy. Once you run PhpDocumentor against your code, look for the errors.html page in the root of your docs. This will list anything PhpDocumentor doesn't like, such as not having file-level docblocks. You could strive to bring that list of errors down to zero.

The third level you could strive to reach would be satisfying any one of the coding standards included in the PHP_CodeSniffer application at PEAR [1]. A drawback here is that these standards more specifically focus on the code itself, but all of the standards do include rules regarding code documentation.

[1] -- http://pear.php.net/package/PHP_CodeSniffer