53

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?

user2418306
  • 2,352
  • 1
  • 22
  • 33
Tom Tresansky
  • 19,364
  • 17
  • 93
  • 129

3 Answers3

68

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.

Lii
  • 11,553
  • 8
  • 64
  • 88
Wesley
  • 10,652
  • 4
  • 37
  • 52
  • 1
    Though it seems to violate the HTML semantics, it seems pretty clear in the documentation you found. – Tom Tresansky Mar 10 '11 at 20:40
  • It does not violate html semantics, it only violates xhtml semantics. – eckes Jan 25 '19 at 15:30
  • 1
    @Wesley: The document that should link to use `

    `, with a lower case p. Maybe it has been updated since you posted your answer. I think you should update your answer too!

     – Lii Jan 03 '20 at 11:59
  • @Lii When referring to HTML 3.x elements, they are specified in all-caps like `

    `. When referring to actual text written in a document (whether .html or Javadoc), you can write and describe the text as `

    ` if you like.

     – AndrewF Apr 22 '20 at 19:04
30

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.

Joshua Taylor
  • 84,998
  • 9
  • 154
  • 353
Joachim Sauer
  • 302,674
  • 57
  • 556
  • 614
  • 7
    Unfortunatelly JDK8 outlaws self-closing
    , what is the alternative?     – eckes Apr 29 '14 at 23:47
  • 1
    @eckes, could you please give a reference to where JDK8 outlaws self-closing
    ?     – Honza Zidek May 18 '14 at 13:58
  • 1
    @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.
    `. I guess the solution is to use the HTML
    (just like I am used to use

    as paragraph seperator instead of block level).

     – eckes May 18 '14 at 22:35
  • @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. – Honza Zidek May 19 '14 at 06:39
  • @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: http://openjdk.java.net/jeps/172 – eckes May 19 '14 at 22:43
  • 6
    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. – spaaarky21 Jul 26 '16 at 16:09
12

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

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

Jin Kwon
  • 20,295
  • 14
  • 115
  • 184
  • 6
    But why?! I have seen it in the code and that's why I am reading answers on this question - someone left `

    ` without `

    ` and it looks okay to others, but not to me ://     – zeroDivider Nov 02 '18 at 11:34
  • 2
    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. `` was not something commonly seen across the Web. – AndrewF Apr 22 '20 at 18:59