Multiple line code example in Javadoc comment

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

---

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

---

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;
}
}

---

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

 is required for preserving lines.
                			                   			

                			                   			

                			                   				{@code must has its own line
                			                   			
                			                   			

                			                   				
 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.
                			                   			
												

												

												
											

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

 and 

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.

---

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.

---

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

---

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

---

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.

---

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.

---

Since Java 18 (JEP 413) you may use @snippet tag:

/**
 * -- ex: looping through List of Map objects --
 * {@snippet :
 * 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"));
 * }
 * }
 *
 * @param query - select statement
 * @return List of Map objects
 */

---

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.

---

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

---

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.

---

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.

---

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.
 ``` */

---