Menu
Which is the more appropriate HTML tag for breaking up paragraphs/long sections of javadoc so according to best practices?
Is it <p /> or <br />? Why?
204
The javadoc TagsRepresents the relative path to the generated document's root directory from any generated page. Adds a comment indicating that this API should no longer be used. Adds a Throws subheading to the generated documentation, with the classname and description text.
Javadoc comment is a multiline comment /* */ that starts with the * character and placed above the class definition, interface definition, enum definition, method definition or field definition.
Go to Project > Generate Javadoc.. in Eclipse (Indigo in my case). You should notice that the "Extra Javadoc options.." text box has the value you must add for the Javadoc exporter to create the HTML equivalent of your tag.
There are no real restrictions on the use of HTML in Javadoc comments. The Javadoc documentation states: Comments are written in HTML - The text must be written in HTML, in that they should use HTML entities and can use HTML tags.
Welcome to the land of HTML 3.2.
According to the official guide on writing doc comments, the correct way to separate paragraphs is with the paragraph tag: <P>. Take a look at the seventh bullet in the section on Format of a Doc Comment.
Ordinarily, I would strongly recommend against using such old, outdated practices for markup. However, in this case, there's a decent reason to make an exception. The Javadoc tool (unless radically updated with custom Doclets) generates old, crufty, somewhat broken markup. Browsers have been built to be backwards-compatible with the crazy old markup of the day, so it makes sense for you to just go along with it. Your use of <P> to separate paragraphs will be in line with the rest of the Javadoc output.
172
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
