Which tag should be used as paragraph separator in Javadoc?

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.


Strictly speaking a self-closing <p /> makes no sense, as <p> should be used to contain a paragraph, i.e. the paragraph should be encased by <p> and </p>.

<br> however is a "lower level" tag that indicates a line break. So the semantically correct way to indicate paragraphs would be to use <p>:

<p>This Foo is used to frobincate a {@link Baz}.</p>
<p>It is quite groovy!</p>

vs.

This Foo is used to frobincate a {@link Baz}.<br>
It is quite groovy!

Visually the <p> results in more whitespace between the lines, while a <br> will just start a new line and not introduce any major whitespace.