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

Patina

Answer 1

<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.

Container

I'd say nested <ul> has to be inside some <li> element, for comparison see w3.org/wiki/HTML_lists#Nesting_lists – Derouen

You can say that, but trying it says something different. – Container

@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. – Induration

I understood that user2622016 meant that You have to write like this: <ul><li><ul>...</ul></li></ul>, so that the innermost <ul>..</ul> is also inside a <li>..</li> block. – Induration

I don't see any difference between example 1 and example 2, so it's hard to say which one is "proper nesting". – Brahui

Sadly, someone with an editing bug up their butt "corrected" the examples, making the answer incomprehensible.The point is that <ul><li>xxx<li>YYY</li></li></ul> will render correctly, but that <ul><li>xxx<ul><li>YYY</li></ul></li></ul>, being correctly nested, is better. – Container

One thing to do, though, is remove the </li> tags. They are not supposed to be there. JavaDoc isn't HTML, although it borrows from it. Same for </p> tags, which you shouldn't use in JavaDoc. – Terrellterrena

@Terrellterrena 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. – Container

Although I cannot find it explicitly stated (and I did look), it's the style that is used in Oracle's documentation. Also, NetBeans complains about it. Intellij, on the other hand, happily adds the </li> tags – Terrellterrena

Answer 2

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.

Terrellterrena

Any references for the omission of the closing tags? – Tews

Yes, here: oracle.com/technetwork/java/javase/documentation/… - although it's implicit rather than explicit. – Terrellterrena

Why do you suggest that omitting the </p> tag is in any way related to not being HTML? It is legal to omit the </p> 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. – Eddie

You're inferring something that I never said. What I said is that you should omit the </p> tags. What's legal or not legal in HTML isn't really that relevant. – Terrellterrena

@Terrellterrena Then why did you say JavaDoc isn't HTML? – Got

Because it isn't. See this question on StackOverflow for more information. There are limitations as to what HTML tags are allowed. – Terrellterrena

This has extra <li> elements before the <ul>, those i would assume should be omitted – Purnell

The <ul> and <li> are nested. – Terrellterrena

Answer 3

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>

Belisle

Your code results in a list with empty items. Though it's properly nested in HTML, the rendered result is ugly. – Topsoil

(¬_¬) In this case, valid HTML seems to be invalid JavaDoc (>ლ) – Fitts

Answer 4

Alternative simpler fast way to keep indentation in javdoc

<pre>...</pre>

In simple words, it renders line formatting as was written.
Better consult it with your team before using it just in case.

e.g. this

/**
* <pre>
* - some element
*    - some other element
*       - yet some other element
* </pre>
*/

will render as such:

 - some element
    - some other element
       - yet some other element

Positives:

• more code readable than multi level HTML nesting
• simple
• fast to type
• keeps line indentation by tab and white spaces
• basically WYSIWYG
• can be used to nicely render a code block by using {@code ...}

Drawbacks:

• soft line wrapping gets adjusted to the longest line inside of <pre>...</pre> block so it requires manual line wrapping

Oversold