Which tag should be used as paragraph separator in Javadoc?

Question

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?

Solution 1

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.

Solution 2

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.

Solution 3

With Java 8, a single starting element(<p>) works.

Note that javadoc doesn't like the closing element (</p>).

Comments

[Péter Török]

Depends on your definition of "nice" I guess. Why not try both out and check the difference in your browser?

[Tom Tresansky]

Hmmmm, I suppose by "display nicely" I mean "follow best practices".

[Tom Tresansky]

Though it seems to violate the HTML semantics, it seems pretty clear in the documentation you found.

[Prashant]

Unfortunatelly JDK8 outlaws self-closing <br/>, what is the alternative?

[Honza Zidek]

@eckes, could you please give a reference to where JDK8 outlaws self-closing <br/>?

[Prashant]

@HonzaZidek as you might know, the changes to JavaDoc in JDK8 are quite far reaching and strict but not very well documented. My "outlawing" was refering to my observation that using it will result in a build-aborting failure as long as you do not suppress it: [ERROR] ....java:24: error: self-closing element not allowed [ERROR] * instances.<br/>. I guess the solution is to use the HTML <br> (just like I am used to use <p> as paragraph seperator instead of block level).

[Honza Zidek]

@eckes: I am not aware of the changes to JavaDoc in JDK8, I'd appreciate if you point me to an article or documentation or anything describing it.

[Prashant]

@HonzaZidek If you are not aware of it, you surely will :) - the whole internet talks about it. Anyway, as I said, there is really no good documentation on the changes Oracle did to the doclint tool in JDK8. The work order is JEP 172: openjdk.java.net/jeps/172

[spaaarky21]

This is great advice for HTML in general but is actually bad advice for Javadocs in particular. javadoc doesn't play well with these modern best practices and newer versions are stricter about accepting markup like this.

[zeroDivider]

But why?! I have seen it in the code and that's why I am reading answers on this question - someone left <p> without </p> and it looks okay to others, but not to me ://

[Prashant]

It does not violate html semantics, it only violates xhtml semantics.

[Lii]

@Wesley: The document that should link to use <p>, with a lower case p. Maybe it has been updated since you posted your answer. I think you should update your answer too!

[AndrewF]

See HTML 3.2. "The end tag is optional as it can always be inferred by the parser." This is a very, very old practice and it looks/looked just fine to many people in the past. </p> was not something commonly seen across the Web.

[AndrewF]

@Lii When referring to HTML 3.x elements, they are specified in all-caps like <P>. When referring to actual text written in a document (whether .html or Javadoc), you can write and describe the text as <p> if you like.