A simpler way to write inline source in Javadoc

Photo by Nathan Cima on Unsplash

A lot of HTML tags are available in Javadoc. After all, the Javadoc tool is supposed to generate HTML pages, so it makes sense that HTML tags are available for use in Javadoc, they can just be passed straight on to the generated HTML pages.

I’ve often written Javadoc like the following excerpt, using the HTML Code tag so that variable or parameter names show up in a monospace font in the generated Javadoc.

    /**
     * @param delta The maximum allowed variance for 
     * <code>expected</code> and <code>actual</code> to differ and 
     * still be considered close enough to be equal.
     */

I think I’ve seen a similar usage of the HTML Code tag in the Java Development Kit (JDK) Javadoc. But when I tried to find examples of that usage for this article, I couldn’t.

Javadoc actually provides a simpler way to mark up as “code” things that take up only one line or less.

    /**
     * @param delta The maximum allowed variance for 
     * {@code expected} and {@code actual} to differ and 
     * still be considered close enough to be equal.
     */

The advantage of this is that then you don’t have to type the HTML Code tag closing, which is very nice if you’re using an integrated development environment (IDE) that doesn’t automatically fill in tag closings (like Apache NetBeans, unlike JetBrains IntelliJ IDEA).

Sure, it’s more work for the Javadoc tool to convert “{@code }” to “<code></code>.” But it’s work that only needs to be done each time you want the Javadoc HTML pages generated. And still the computer can do it faster and more reliably than you can.

However, do note that if what you need to mark up as “code” takes up more than one line, you still need to use the HTML Code tag directly. You can find examples of this in JDK source, for example, in the Javadoc for thereplaceFirst() function in the java.lang.String class.