CODEWITHSUNDEEP
documentationjavadocindentationnested-lists
James Raitsev
James Raitsev

Reputation: 96391

How to create multiple levels of indentation in Javadoc?

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:

Upvotes: 141

Views: 112182

Answers (4)

GreenMarty
GreenMarty

Reputation: 382

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

Upvotes: 0

SeverityOne
SeverityOne

Reputation: 2691

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.

Upvotes: 56

Drew Noakes
Drew Noakes

Reputation: 310832

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>

Upvotes: 7

Charlie Martin
Charlie Martin

Reputation: 112356

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

Upvotes: 199

Related Questions