-- Matthew Ratzloff <[EMAIL PROTECTED]> wrote (on Friday, 05 January 2007, 08:09 AM -0800): > This is fine, except you will occasionally get situations like this: > > * @param Zend_Controller_Router_Route_Interface $param2 OPTIONAL > Description goes here (default: false) > * @param array $flags An array of flags. > > Lining those up is unwieldy. I generally line up the second word > (everything after @param, @return, etc.) and don't align anything else for > this reason.
This is what I do as well; I've found aligning after that, as you show, leads to either long lines or wrapped lines. > I also think the optional description could be something more readable, > such as: > > "Optional; description goes here (default: false)" How you format 'Optional; ' is how I'd prefer it; I don't really like ALL CAPS. > ----- Original Message ----- > From: "Thomas Weidner" <[EMAIL PROTECTED]> > To: "Gavin Vess" <[EMAIL PROTECTED]> ; <[email protected]> > Sent: Thursday, January 04, 2007 12:27 AM > Subject: Re: [fw-general] Coding Standard Discussion Thread - Docblock > Standardization > > > > > 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? > > > > Erase only the hypen... > > > > * @param bool $param2 OPTIONAL Description goes here (default: false) > > * @param string|array $flags A flag or array of flags. > > > > But let the whitespaces to the description of the parameter. > > So all parameter descriptions are at the same intention. > > So phpdoc should work correct, and the pure API doc is also more readable -- Matthew Weier O'Phinney PHP Developer | [EMAIL PROTECTED] Zend - The PHP Company | http://www.zend.com/
