Further review please

[Brent Putman]

Just catching up on some old email threads


On 7/11/11 11:57 AM, Chad La Joie wrote:
> Comments:
> - You don't need to use <br/>s in javadoc, just insert a blank line
> 


Are you sure about this?  Based on what I have observed in the past, and
also on some quick googling, literal line breaks in the source code are
not preserved in Javadocs, since it gets rendered as HTML which of
course doesn't respect linebreaks.  Your nicely formatted paragraphs
therefore get all smushed together into one long one in the Javadoc.  I
have made a habit of always using <p>...</p> around paragraphs in
Javadoc, especially where there's lots of text involved and the
concatenation looks really bad without it.

I suppose a nice Javadoc option (or maybe an Eclipse and/or Maven
javadoc plugin option) would be to turn all double newlines into <p>
blocks for you, so you wouldn't have to remember to do it.  But I'm not
aware of such an option.