Partner – Microsoft – NPI (cat=Java)
announcement - icon

Microsoft JDConf 2024 conference is getting closer, on March 27th and 28th. Simply put, it's a free virtual event to learn about the newest developments in Java, Cloud, and AI.

Josh Long and Mark Heckler are kicking things off in the keynote, so it's definitely going to be both highly useful and quite practical.

This year’s theme is focused on developer productivity and how these technologies transform how we work, build, integrate, and modernize applications.

For the full conference agenda and speaker lineup, you can explore JDConf.com:

>> RSVP Now

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, &lt; 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:

 

method1

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:

 

method2

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

method3
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&lt;String&gt;</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);
}

 

method4

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.

Course – LS (cat=Java)

Get started with Spring and Spring Boot, through the Learn Spring course:

>> CHECK OUT THE COURSE
res – REST with Spring (eBook) (everywhere)
Comments are closed on this article!