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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »



Since JDK 8, a doclint tool was introduced, 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 is a really nice tool but it has no mercy for developpers and will punish you with a compilation error for a tiny Javadoc detail but don't worry, this guide will show you how to get rid of the majority of the doc linter errors and warnings. 

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

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

@code has the same effect of @litteral plus changes the font to a code 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; ('{') and &#125; for ('}'). 

   

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

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

As mentionned 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>
 */


Do not use end closing slashes in self closing tags (`<p/>`, `<br/>`)

End closing slashes in self closing tags (`<p/>`, `<br/>` ...) are not tolerated by the doc linter, simply write your self closing tag like this: `<p>`, `<br>`...


Paragraph (`<p>`) cannot be empty

It is not allowed to have a `<p>` tag followed by nothing. You would not give an empty box gift box to someone, would you? 


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.



  • No labels