On Fri, 4 Jan 2008, Raymond Bosman wrote: > > > I remember that we decided not to repeat the information of the short > > desc in the long version. But I can't see what it has to do with the > > newline? > > The newline won't be correct if the first and second sentence belong in the > same paragraph. > > You may be right that we never decided about the newline, though. > > > Is the newline justified in the next example? > > /** > * Generates a unique hash from the current options. > * For example the default values return: > * <code> > * 1. "updqr0" > * </code> > */
It doesn't matter really, as phpdoc will split it in a short description: Generates a unique hash from the current options. And a long description: * For example the default values return: * <code> * 1. "updqr0" * </code> PHPDoc always uses the first line *only* as short description, and different bits end up on different places in the docs. See the documentation of __construct of ezcQuery. In the list it is shows as just the first line: http://ezcomponents.org/docs/api/2007.2/Database/ezcQuery.html#sec-method-summary In the description of the method, with both parts: http://ezcomponents.org/docs/api/2007.2/Database/ezcQuery.html#__construct This happens whether or no single new line is in between them. Because it makes it a bit more transparent what happens, *if* the new line is there in the docblock, I would prefer that over no new-line. But I don't think it's important enough to pro-actively change it. regards, Derick -- Components mailing list [email protected] http://lists.ez.no/mailman/listinfo/components
