Add a Reference to Method Parameters in Javadoc

1. Overview

In the Java language, we can generate documentation in HTML format from Java source code using Javadoc. In this tutorial, we'll learn about different ways to add a reference to method parameters in Javadoc.

2. Different Ways to Add a Reference to a Method Parameter

In this section, we'll talk about adding a reference to a method parameter in Javadoc. We'll see the usage of inline tag {@code} and HTML style tag </code> in Javadoc.

Further, we'll see how {@code} and <code> tag take care of a few special cases:

• displaying special characters ‘<‘, ‘>', and ‘@'
• indentation and line breaks
• handling of escaping of HTML codes — for example, < which translates to symbol ‘<‘

2.1. The {@code} Tag

{@code text} is an inline tag that was included in JDK 1.5.

The {@code} tag formats literal text in the code font. {@code abc} is equivalent to <code>{@literal abc}</code>.

We don't need to manually escape any special character used inside the {@code} tag.

When we use the {@code} tag, it:

• displays ‘<‘ and ‘>' correctly
• displays ‘@' correctly
• does not need to escape special characters via HTML number codes
• is more readable and concise

Let's create a simple method in a class and add some Javadoc using the {@code} tag:

/**
  * This method takes a {@code String} 
  * and searches in the given list {@code List<String>}
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}

Here, we can see that we don't need to escape the special characters ‘<‘ and ‘>'.

The generated Javadoc will render the HTML output as:

Similarly, we can see that we don't need to escape the ‘@' character:

/**
  * This is sample for showing @ use without any manual escape.
  * {@code @AnyAnnotaion}
  * 
  */
public void javadocTest() {
}

This will render to HTML Javadoc as:

In the case of a multiline code snippet in Javadoc, {@code} will not maintain the indentation and line break. To overcome this, we can use HTML tag <pre> along with {@code}. However, we need to escape the ‘@' character in this case.

2.2. The <code> Tag

<code> is an HTML style tag supported by Javadoc.

When we use the <code> tag, it:

• doesn't display ‘<‘ and ‘>' correctly
• requires to escape special characters via HTML number codes
• is not so readable

Let's consider the same example again. We can see that the generated Javadoc HTML is missing the <String> parameterized type after List in our paragraph:

/**
  * This method takes a <code>String</code>
  * and searches in the given <code>List<String></code>
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}

Here, if we escape the special characters ‘<‘ and ‘>' in our method comment, then it will render the correct <String> in Javadoc:

/**
  * This method takes a <code>String</code>
  * and searches in the given <code>List<String></code>
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}

3. Conclusion

In this tutorial, we first talked about how to use {@code} and <code> to reference method parameters in Javadoc. Then we described the handling of special characters by these tags. In conclusion, we now understand how to add references to method parameters in Javadoc, and we can see that {@code} is better than <code> any day.