PHPDoc Usage

[gondwanasoft]

Adopt a minimum standard for PHPDoc and other source code comments, including:

1. circumstances in which a method may fail and the consequences of this
2. method preconditions; eg, ‘Method x() must have been called’; ‘Global variable y must have been initialised’
3. necessary post-conditions; eg, ‘After calling this method, you must free z’
4. all possible return values and types (‘mixed’ is unacceptable) for the method—including error conditions
5. all possible exceptions thrown by the method, including those thrown by lower-level methods that aren’t caught
6. if method is deprecated, notes on what to use instead.

This should be mandatory for public and protected methods, and strongly encouraged for private methods.