How to create multiple levels of indentation in Javadoc?

Question

Suppose, that as part of documenting your code (Javadoc) you want to indicate that the relationships between elements using deep indentation.

How can I create a nested list as:

some element
- some other element
  - yet some other element

Charlie Martin · Accepted Answer · 2016-08-09T14:51:54.473

187

<ul>
  <li>Element</li>
  <ul>
     <li>Subelement...</li>

You can pretty freely use HTML inside javadoc comments.

Update: Because it came up, I tried

<ul>
    <li>one</li>
    <ul>
        <li>one point one</li>
    </ul>   
</ul>

and get

one

one point one

I agree proper nesting is better.

edited Aug 09 '16 at 14:51

answered Jun 25 '11 at 15:45

Charlie Martin

110,348
25
193
263

2
I'd say nested
- element, for comparison see http://www.w3.org/wiki/HTML_lists#Nesting_lists
– user2622016 Sep 05 '13 at 08:37
You can say that, but trying it says something different. – Charlie Martin Sep 06 '13 at 19:46
2

@Charlie Instead of saying "I agree proper nesting is better.", maybe You could write an example showing how to properly nest? Otherwise, maybe some beginner will not understand Your comment and use the above-mentioned form. – Rauni Lillemets Apr 24 '14 at 07:35
2
I understood that user2622016 meant that You have to write like this:
- ...
, so that the innermost
is also inside a
..

Rauni Lillemets

Apr 25 '14 at 11:59

I don't see any difference between example 1 and example 2, so it's hard to say which one is "proper nesting". – Noumenon Nov 20 '16 at 04:46

Sadly, someone with an editing bug up their butt "corrected" the examples, making the answer incomprehensible.The point is that `

xxx
YYY

` will render correctly, but that `

xxx
- YYY

`, being correctly nested, is better. – Charlie Martin Nov 20 '16 at 08:40

3

One thing to do, though, is remove the `` tags. They are not supposed to be there. JavaDoc isn't HTML, although it borrows from it. Same for `` tags, which you shouldn't use in JavaDoc. – SeverityOne Apr 18 '18 at 06:47

@SeverityOne that wasn't the case when I was a Java Architect at Sun, and reviewing the standard I don't immediately see anything to that effect now, so I guess I'd like a citation. – Charlie Martin Apr 18 '18 at 19:23

3

Although I cannot find it explicitly stated (and I did look), it's the style that is used in [Oracle's documentation](http://www.oracle.com/technetwork/java/javase/tech/index-137868.html). Also, NetBeans complains about it. Intellij, on the other hand, happily adds the `` tags – SeverityOne Apr 18 '18 at 20:37

score 51 · Answer 2 · answered Apr 18 '18 at 06:51

51

The correct way is as follows:

/**
 * <ul>
 *   <li>some element
 *   <li><ul>
 *     <li>some other element
 *     <li><ul>
 *       <li>yet some other element
 *     </ul>
 *   </ul>
 * </ul>
 */

Although JavaDoc borrows from HTML, it isn't HTML, and you should omit the </li> tags, just as you should omit </p> tags.

answered Apr 18 '18 at 06:51

SeverityOne

2,476
12
25

4

Any references for the omission of the closing tags? – friederbluemle Jun 28 '18 at 04:44
5

Yes, here: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples - although it's implicit rather than explicit. – SeverityOne Jun 30 '18 at 17:35
Why do you suggest that omitting the tag is in any way related to not being HTML? It is legal to omit the tag in HTML under most circumstances. That was even common practice when HTML was commonly edited "by hand" as is still the case for javadoc. – SensorSmith Sep 03 '21 at 22:59
1

You're inferring something that I never said. What I said is that you should omit the tags. What's legal or not legal in HTML isn't really that relevant. – SeverityOne Sep 07 '21 at 13:00
@SeverityOne Then why did you say JavaDoc isn't HTML? – xehpuk Feb 04 '22 at 19:45
1

Because it isn't. See [this question on StackOverflow](https://stackoverflow.com/questions/16481230/allowed-html-tags-in-javadoc) for more information. There are limitations as to what HTML tags are allowed. – SeverityOne Feb 05 '22 at 20:57
This has extra
elements before the

jediwompa

May 04 '23 at 18:01

The `

` are nested.

– SeverityOne May 05 '23 at 06:43

score 7 · Answer 3 · answered Sep 18 '16 at 14:24

7

The nested list should be within its own <li>. <ul> is not a valid child element of <ul>.

So your example would be:

<ul>
  <li>some element</li>
  <li>
    <ul>
      <li>some other element</li>
      <li>
        <ul>
          <li>yet some other element</li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

answered Sep 18 '16 at 14:24

Drew Noakes

300,895
165
679
742

Your code results in a list with empty items. Though it's properly nested in HTML, the rendered result is ugly. – naXa stands with Ukraine Apr 27 '18 at 12:41
(¬_¬) In this case, valid HTML seems to be invalid JavaDoc (>ლ) – Top-Master Jan 18 '21 at 20:42

How to create multiple levels of indentation in Javadoc?

3 Answers3

Linked