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