137

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

4 Answers 4

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

9
  • 2
    I'd say nested <ul> has to be inside some <li> element, for comparison see w3.org/wiki/HTML_lists#Nesting_lists Sep 5, 2013 at 8:37
  • 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. Apr 24, 2014 at 7:35
  • 2
    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. Apr 25, 2014 at 11:59
  • 3
    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. Apr 18, 2018 at 6:47
  • 3
    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 Apr 18, 2018 at 20:37
52

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.

8
  • 4
    Any references for the omission of the closing tags? Jun 28, 2018 at 4:44
  • 5
    Yes, here: oracle.com/technetwork/java/javase/documentation/… - although it's implicit rather than explicit. Jun 30, 2018 at 17:35
  • 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. Sep 3, 2021 at 22:59
  • 1
    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. Sep 7, 2021 at 13:00
  • 1
    Because it isn't. See this question on StackOverflow for more information. There are limitations as to what HTML tags are allowed. Feb 5, 2022 at 20:57
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>
2
  • Your code results in a list with empty items. Though it's properly nested in HTML, the rendered result is ugly. Apr 27, 2018 at 12:41
  • (¬_¬) In this case, valid HTML seems to be invalid JavaDoc (>ლ)
    – Top-Master
    Jan 18, 2021 at 20:42
0

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.