Which tag should be used as paragraph separator in Javadoc?

java comments javadoc
Tom Tresansky picture Tom Tresansky · Mar 10, 2011 · Viewed 42.7k times · Source

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

Wesley picture Wesley · Mar 10, 2011

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.

Related questions

/** and /* in Java Comments

What's the difference between /** * comment * * */ and /* * * comment * */ in Java? When should I use them?

Read More
Javadoc: line breaks without HTML-tags?

Sorry for a probable FAQ kind of question, but I just can't find the answer. As far as I remember Eclipse, a blank line in a Javadoc comment is displayed (in in-source Javadoc popups) as a line break (with extra …

Read More
Details of difference between @see and @inheritDoc

I have looked over JavaDoc reference, and while I understand basic difference between @see (various links) and {@inheritDoc} (export of superclass JavaDoc comment), I need clarification on how things actually implemented. In Eclipse IDE when I select “Generate Element Comments” …

Read More