Rectangle 27 0

java Multiple line code example in Javadoc comment?


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

@jpdaigle I just tried this in Eclipse Galileo and Helios and the formatter does not replace anything for me (on Mac OS, but I have never seen the formatter do anything like that on other platforms either).

Another unfortunate, if you have blocks in your example code using curly braces "{}", the first closing brace will terminate the @code block. One way around it is to use (wait for it...) html entities for the braces. I don't see a compelling argument for <pre> tags for code with blocks.

I would have thought so too, but unfortunately it doesn't, you still need to add the <pre> tag to get line breaks.

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

Unfortunately, it seems when you hit ctrl+shift+F (Format code in Eclipse), Eclipse messes up the {@code} tag and replaces it with {code ...

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

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


/** 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
  */
new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();
  • 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
  • usage of "new" {@code ...} - tag to get the generics included in the output
  • usage of old <code> - tag to prevent the curly brackets from being interpreted

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:

This works but I get a warning when running javadoc outputting this warning "warning: {@code} within <code>"

gets printed as

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


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

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

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

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

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

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

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

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


....
 * 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>
...
</pre></blockquote></p>
<p><blockquote><pre>
<pre><blockquote>...</blockquote></pre>

@JinKwon sadly this is not always working, not in my code snippet :( adding an {@code at the beginning works, even if the closing } will not be reached

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

This appears to work for most code, but does not escape angular brackets such as in List<String>. For that I'm using <pre>{@code ... }</pre>.

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


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

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

Displays with line breaks:

Welcome on Stack Overflow. To format code in posts, you can either prefix it (on a separate paragraph) by four spaces, or surround them by backticks (`` ... ``). You don't need <code> and <pre> tags. I edited your answer in this mind.

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.

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


E.g.:
List<MyClass> myObject = null;
List myObject = null;
List<MyClass> myObject = null;

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.

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


<pre></pre>
Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


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

UPDATE with JDK8

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

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

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

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


<pre class=prettyprint>

TODO:your code.

</pre>

@tyblu Android Studio works,but Xamarin Studio/VS maybe not work.You can have a try.

If you are Android developer you can use:

Please explain: what in Android's tools should make this work, considering the issues that require the @code tag? And which component should define the prettyprint class? Android uses regular Javadoc.

To pretty print your code in Javadoc with Java code.

Xamarin/VS, Android Studio, or does it not matter?

Note
Rectangle 27 0

java Multiple line code example in Javadoc comment?


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.

Note