Child pages
  • How to write JDK 8 compliant Javadoc
Skip to end of metadata
Go to start of metadata

The doclint tool has been introduced in JDK 8. It "reports warnings for bad references, lack of accessibility and missing Javadoc comments, and reports errors for invalid Javadoc syntax and missing HTML tags". 

This tool is already enabled for OpenDJ and will probably be enabled for other products in the future. 

This guide will help you to fix the most frequent Doclint errors and warnings you may find.

Wrap less-than (<) and greater-than (>) symbols in @literal or @code tags

@literal and @code will ensure enclosed text does "not containing HTML markup or nested javadoc tags"

@code does the same as @literal but also changes the font to a monospace font. 

Example:

/**
 * Returns {@code true} if the provided integer is not null and non-negative.
 * It does the following: {@code return (i != null && i >= 0);}. 
 * @param i 
 *			an integer. 
 * @return {@code true} if i is not null and {@literal i >= 0}, false otherwise.
 */


Pitfall:

You cannot add curly braces within simple or double quotes in @literal or @code tags. You will have to use the HTML escape characters for curly braces instead: &#123; for { and &#125; for }.

Wrap code blocks in <pre> tags and @code tags

The HTML tag <pre> is not mandatory for code blocks, though it will greatly improve the layout in the browser. The <pre> tag will make the browser keep indentation and new lines within the tag. If you omit it, it might display several lines of code on the same line.

As mentioned earlier, the @code tag allows you to freely use HTML reserved characters and will change the font to a code font. 

Example:

/**
 * <pre>
 * {@code
 * int i = 0;
 * while (i <= 10) {
 * 	i++;
 * }
 * }
 * </pre>
 */

Paragraph (<p>) and self closing tags (<p/><br/>)

Line breaks between paragraphs can be performed using paragraph or line break HTML tags. The only limitation is that the tags used must be valid HTML. The use any of the following:

  • <p>
  • <br>
  • <p></p>

The following tags are not valid HTML and are not allowed:

  • <p/>
  • <br/>

For more details, see the Oracle Javadoc reference and a JDK ticket clarifying the use of the <p> tag.

HTML links must be valid and on a single line. 

You can add an HTML link with the <a> tag but the link must be a valid URI and written on a single line.



That's it, applying these rules will fix most of the Doclint errors and warnings, you can find more information about Javadoc and Doclint.

  • No labels