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, Java SE 8 tag descriptions can be found here: Javadoc Tags)

Answer 2

I had a really tough time with including a specific code example in a javadoc comment. I'd like to share this one.
Please note the following:

• usage of old <code> - tag to prevent the curly brackets from being interpreted
• usage of "new" {@code ...} - tag to get the generics included in the output
• escaping of the @ sign in @Override via "{@literal @}Override" because javadoc generator "tilts" there due to the fact that the @ goes directly after an opening curly bracket
• remove one space in front of {@code and {@literal, to compensate inner spaces and keep the alignment

javadoc code:

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

gets printed as

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Answer 3

The java source has lots of good examples for this. Here's an example from the head of "String.java":

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

Answer 4

Enclose your multiline code with <pre></pre> tags.

Answer 5

You need the <pre></pre> tags for the line breaks, and the {@code ... } inside them for generics. But then it's not allowed to place the opening brace on the same line as the <generic> tag, because then everything will be displayed on 1 line again.

Displays on one line:

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

Displays with line breaks:

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

Another weird thing is when you paste the closing brace of {@code, it gets displayed:

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

Output:

public List<Object> getObjects() 
{
   return objects;
}
}

Answer 6

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/

• <pre/> is required for preserving lines.
• {@code must has its own line
• <blockquote/> is just for indentation.

public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

---

UPDATE with JDK8

The minimum requirements for proper codes are <pre/> and {@code}.

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

yields

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

And an optional surrounding <blockquote/> inserts an indentation.

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

yields

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

Inserting <p> or surrounding with <p> and </p> yields warnings.

Answer 7

I was able to generate good looking HTML files with the following snip-it shown in Code 1.

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(Code 1)

Code 1 turned into the generated javadoc HTML page in Fig 1, as expected.

A-->B
 \
  C-->D
   \   \
    G   E-->F

(Fig. 1)

However, in NetBeans 7.2, if you hit Alt+Shift+F (to reformat the current file), Code 1 turns in to Code 2.

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(Code 2)

where the first <pre> is now broken onto two lines. Code 2 produces generated javadoc HTML file as shown in Fig 2.

< pre> A-->B \ C-->D \ \ G E-->F

(Fig 2)

Steve B's suggestion (Code 3) seems to give the best results and remains formatted as expected even after hitting Alt+Shift+F.

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(Code 3)

Use of Code 3 produces the same javadoc HTML output as shown in Fig 1.

Answer 8

Here's my two cents.

As the other answers already state, you should use <pre> </pre> in conjuction with {@code }.

Use pre and {@code}

• Wrapping your code inside <pre> and </pre> prevents your code from collapsing onto one line;
• Wrapping your code inside {@code } prevents <, > and everything in between from disappearing. This is particularly useful when your code contains generics or lambda expressions.

Problems with annotations

Problems can arise when your code block contains an annotation. That is probably because when the @ sign appears at the beginning of the Javadoc line, it is considered a Javadoc tag like @param or @return. For example, this code could be parsed incorrectly:

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

Above code will disappear completely in my case.

To fix this, the line must not start with an @ sign:

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

Note that there are two spaces between @code and @Override, to keep things aligned with the next lines. In my case (using Apache Netbeans) it is rendered correctly.

Answer 9

There is a significant difference between <blockquote><pre>... and <pre>{@code.... The former will omit the type declarations in generics but the latter will keep it.

E.g.: List<MyClass> myObject = null; displays as List myObject = null; with the firts and as List<MyClass> myObject = null; with the second

Answer 10

If you are Android developer you can use:

<pre class=”prettyprint”>

TODO:your code.

</pre>

To pretty print your code in Javadoc with Java code.

Answer 11

I just read the Javadoc 1.5 reference here, and only the code with <and > must be enclosed inside {@code ...}. Here a simple example:

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...

Answer 12

Try replacing "code" with "pre". The pre tag in HTML marks the text as preformatted and all linefeeds and spaces will appear exactly as you type them.

Answer 13

Using Java SE 1.6, it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc:

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

is the simplest way to do this.

An Example from a javadoc I got from a java.awt.Event method:

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

This produces output that looks exactly like the regular code, with the regular code spacings and new lines intact.

Answer 14

In Visual Studio Code at least, you can force a Javadoc comment to respect line-breaks by wrapping it in triple-backticks, as seen below:

/** ```markdown
 * This content is rendered in (partial) markdown.
 * 
 * For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
 * Bonus: it keeps single line-breaks, as seen between this line and the previous.
 ``` */

Answer 15

I work through these two ways without any problem:

<pre>
<code>
 ... java code, even including annotations
</code>
</pre>

and

<pre class="code">
 ... java code, even including annotations
</pre>

Of course the latter is more simplest and observe the class="code" part

Answer 16

A combination of two of the other solutions seems perfect:

* <pre>{@code
*     {@literal @}Override
*     public void someMethod() {
*         Set<String> s;
*     }
* }</pre>

ie. use <pre>{@code to start and }</pre> to end the snippet. Also, replace @ with {@literal @}.

Haven't found an easier solution. Quite sad for a language that has been under active development for decades.

Answer 17

I enclose my example code with <pre class="brush: java"></pre> tags and use SyntaxHighlighter for published javadocs. It doesn't hurt IDE and makes published code examples beautiful.