Is it a good or bad practice to use HTML in javadoc comments?
When I look at the comments of java methods they all look nicely formatted with the name of method at the top followed by the entire method header, but when I add javadoc to my methods it's hardly readable (I mean the information that pops up when using the autocomplete when writing code).
So I tried adding HTML to the javadoc comments. It looks better, but then when I generate the javadoc and look at the comments in the browser the layout is all messed up.
Also adding the HTML makes my comments hard to read when reading it directly in the code.
Example of my commment:
/**
* <br/>
* <li><b><i>hasChanged</i></b></li>
* <br/><br/><br/>
*
* <pre>public void hasChanged(boolean changed)</pre>
* <br/>
*
* This method can notify the observers when a change has occurred in a model.
* <br/><br/>
*
* The observer can then set the right controls
* <br/><br/>
*
* @param changed
* <br/><br/>
* Pass true if a model has been changed from it's starting values <br/><br/>
* Pass false if the model has it's initial values<br/><br/>
*/
Are there some best practices how to write comments in java so it is nicely formatted and readable from both the javadoc in the browser as reading it directly from the code?
Also are there any guidelines as to the text comments should contain? E.g. Comments for methods should always start with 'This method.." or something.