Multiple line code example in Javadoc comment

Question

I have a small code example I want to include in the Javadoc comment for a method.

/**  * -- ex: looping through List of Map objects --  * <code>  * for (int i = 0; i < list.size(); i++) {  *      Map map = (Map)list.get(i);  *      System.out.println(map.get("wordID"));  *      System.out.println(map.get("word"));  * }  * </code>  *   * @param query - select statement  * @return List of Map objects  */ 

The problem is the code example shows up in the Javadoc with no line breaks making it hard to read.

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); }  Parameters query - - select statement  Returns: List of Map objects  

I guess I am wrong in assuming the code tag would handle line breaks. What is the best way to format code examples in Javadoc comments ?

Answer 1

In addition to the already mentioned <pre> tags, you should also use the @code JavaDoc annotation, which will make life much easier when it comes to HTML entities issues (in particular with Generics), e.g.:

* <pre> * {@code * Set<String> s; * System.out.println(s); * } * </pre> 

Will give correct HTML output:

Set<String> s; System.out.println(s); 

While omitting the @code block (or using a <code> tag) will result in HTML like this:

Set s; System.out.println(s); 

For reference, a full list of tag descriptions available in Java SE 8 can be found here.