I do like the visual separation achieved by the hyphen in the PHP source
code, but am not attached to any particular way of accomplishing such
separation. I read code, and rarely ever bother reading the extracted
phpdoc summary, as I usually want to also see the function's definition.
Any ideas on alternative ways to accomplish the visual separation of
parameter descriptions without using a hyphen?
Cheers,
Gavin
Matthew Weier O'Phinney wrote:
-- Gavin Vess <[EMAIL PROTECTED]> wrote
(on Tuesday, 02 January 2007, 02:18 PM -0800):
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.
I like the 'OPTIONAL' tagging -- I do the same in my code (but not usu.
all caps). I do *not* like the hyphen. It's redundant to how phpdoc
processes the documentation.
