A Guide to Formatting Code Snippets in Javadoc

Sometimes you want to add code snippets to our Javadoc comments, especially when developing an API of some kind. But how do you mark the code snippet so that it will be rendered correctly in the final Javadoc HTML, especially when special characters like '<', '>' and '@' are involved? Since there are multiple options to do this - each with different results - this blog post gives an overview on these options and a guideline on when to use which.

<pre>, <code>, {@code}, what?

Javadoc supports three different features for code markup. These are the HTML tags <pre> and <code> and the Javadoc tag {@code}. Sounds great, but each time I want to include a code snippet into a Javadoc comment, I’m wondering which of the three to use and what the difference between them actually is… .

To assemble a definitive guide on when to use which of the markup features, I took a look at how they behave by answering the following questions for each of them:

<pre>

<pre> is the default HTML tag for preformatted text. This means that HTML renderers by default know that the code within the tag should be displayed literally. Thus, line breaks and indentation are supported. However, since we’re in a Javadoc environment, '@' is evaluated as a Javadoc tag and since we’re also in an HTML environment, '<' and '>' are evaluated as HTML tags. So none of these characters will be displayed correctly in the rendered Javadoc HTML so they have to be escaped.

/**
 * <pre>
 * public class JavadocTest {
 *   // indentation and line breaks are kept 
 * 
 *   &#64;SuppressWarnings
 *   public List&#60;String&#62; generics(){
 *     // '@', '<' and '>'  have to be escaped with HTML codes
 *     // when used in annotations or generics
 *   }
 * } 
 * </pre>
 */
public class PreTest {}

renders to …

public class JavadocTest {
   // indentation and line breaks are kept 
 
   @SuppressWarnings
   public List<String> generics(){
     // '@', '<' and '>'  have to be escaped with HTML codes
     // when used in annotations or generics
   }
 } 

<code>

Within a <code> tag, not even the indentation and line breaks are kept and our special characters still have to be escaped.

/**
 * Using <code>, indentation and line breaks are lost. 
 * '@', '<' and '>'  have to be escaped with HTML codes.
 * 
 * An annotation <code>&#64;Foo</code>; and a generic List&#60;String&#62;.
 */
public class CodeHtmlTagTest {}

renders to …

Using <code>, indentation and line breaks are lost. '@', '<' and '>' have to be escaped with HTML codes. An annotation @Foo; and a generic List<String>.

{@code}

{@code} is a Javadoc tag that came with Java 5. A code snippet embedded within {@code} will display our special characters correctly so they don’t need to be manually escaped. However, indentation and line breaks will be lost. This can be rectified by using {@code} together with <pre>, though (see next section).

/**
 * Using {@code @code} alone, indentation will be lost, but you don't have to
 * escape special characters:
 * 
 * {@code An annotation <code>@Foo</code>; and a generic List<String>}.
 */
public class CodeJavadocTagTest {}

renders to …

Using @code alone, indentation will be lost, but you don't have to escape special characters: An annotation <code>@Foo</code>; and a generic List<String>.

<pre> + {@code}

Combining <pre> and {@code}, indentations and line breaks are kept and '<' and '>' don’t have to be escaped. However, against all expectations the '@' character is now evaluated as a Javadoc tag. What’s worse: it cannot even be escaped using the HTML number code, since the HTML number code would be literalized by {@code}.

/**
 * <pre>{@code 
 * public class JavadocTest {
 *   // indentation and line breaks are kept 
 * 
 *  @literal @SuppressWarnings
 *   public List<String> generics(){
 *     // '<' and '>'  are displayed correctly
 *     // '@' CANNOT be escaped with HTML code, though!
 *   }
 * } 
 * }</pre>
 */
public class PreTest {}

renders to …

public class JavadocTest {
    // indentation and line breaks are kept 
  
    @SuppressWarnings
    public List<String> generics(){
      // '<' and '>'  are displayed correctly
      // '@' CANNOT be escaped with HTML code, though!
    }
  }

Note that you actually CAN escape an '@' using @literal @ within the {@code} block. However, this way always renders an unwanted whitespace before the '@' character, which is why I don’t discuss that option any further.

Code Markup Features at a Glance

The following table summarizes the different javadoc code markup features.

…

{@code …}

When to use which?

Looking at the table above, sadly, there is no single best option. Which option to use depends on the content of the code snippet you want to embed in your Javadoc. The following guidelines can be derived for different situations: