Tom Tresansky Tom Tresansky - 7 months ago 27
Java Question

Which tag should be used as paragraph separator in Javadoc?

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?

Answer

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.

Comments