Gavin Vess wrote:
These suggestions look good to me, and seem to summarize standards used
by the better commented classes already in the framework.
Regarding method comments, I like Thomas' approach using the word
OPTIONAL for optional parameters, and then adding the default value thusly:
* @param bool $param2 - OPTIONAL Description goes here
(default: false)
* @param string|array $flags - A flag or array of flags.
I also like Thomas' style of lining things up under a hyphen, making a
clear visual distinction between the names of the parameters and their
descriptions.
+1 on this, even Zend Studio will pop up the OPTIONAL stuff in the
phpdoc info popups.. which is good stuff.
I will add this and the other feedback to the standard docblock file
tonight and send back to the list for version2.
-ralph
