7 Best Practices for Java API Documentation

The?Javadoc Tool?simplifies the documentation process in Java, allowing developers to document their code seamlessly as they write it. This article delves into 7 best practices for generating API documentation from Java source files using?Javadoc.

1. Follow the Comment Specification for Your Java Version

The tool uses a JavaDoc?doclet?to analyze the internal structure of the source files and produce corresponding output files.?The standard?doclet?generates HTML output, but it is possible to produce different outputs using different?doclets.

The comments recognized by the standard?doclet?are defined in the?Comment Specification?for Java 17. Note that the specification may vary between different Java versions.

2. Add Class-Level Comments With @author and @since

It’s always nice to include authors and contributors when creating a class, using the?@author?tag.

In some cases, like when you create artifacts like libraries, it is good practice to include the version in which the class was introduced with the?@since?tag.

/**
 * Methods for manipulating strings.
 *
 * @author David Buster
 * @author Annie Lonny
 * @author Jessamine Gerónimo
 * @since 1.0
 */
public class StringUtils { ... }        

The code above generates the following HTML documentation:

3. Add Method-Level Comments Including Inputs (@param) and Outputs (@return and @throws)

Make sure to include the parameters required by the method using the?@param?tag.

Include the possible outcomes, a returned value or an exception, using the?@return?and?@throws?tags.

/**
 * Returns a formatted decimal using the specified decimal pattern and argument.
 *
 * @param pattern  The pattern for the string format.
 * @param argument The object to format.
 * @return The formatted decimal.
 * @throws java.lang.IllegalArgumentException If the pattern is incompatible with the given argument.
 * @since 1.1
 */
public static String formatDecimal(String pattern, Object argument)
    throws IllegalArgumentException { ... }        

The code above generates the following HTML documentation:

4.?Reference Related Classes and Methods With?@see and {@link}

Add inline links using the?{@link}?tag and references using?@see?for the specified module, package, class, or member of a referenced class.

Both tags accept the same syntax for?module/package.class#member label.

/**
 * Returns the total with the currency symbol and the formatted decimal amount.
 *
 * @param currency {@link Currency} in which the amount is expressed.
 * @param amount   the total amount in {@link BigDecimal}.
 * @return The total using currency symbol and decimal format, e.g. $100,000.00.
 * @see #formatDecimal(String, Object)
 * @since 1.2
 */
public static String formatTotal(Currency currency, BigDecimal amount) { ... }        

The code above generates the following HTML documentation:

5. Use HTML

Use?HTML 5?tags in comments to generate more comprehensive documentation.

/**
 * Returns the formatted phone number based on the following patterns:
 * <ul>
 * <li>Pattern for 10-digit numbers: <em>(XXX) XXX-XXXX</em></li>
 * <li>Pattern for 7-digit numbers: <em>XXX-XXXX</em></li>
 * </ul>
 * <p><b>Note: The method will remove any non-digit characters from the input string.</b>
 *
 * @param phoneNumber the string phone number.
 * @return the formatted phone number.
 * @since 1.3
 */
public static String formatPhoneNumber(String phoneNumber) { ... }        

The code above generates the following HTML documentation:

6.?Format Code Snippets With?{@code} and <pre></pre>

Add inline code snippets using the?{@code}?tag,?this displays the text in code font without interpreting it as HTML or nested Javadoc tags.

The?<pre></pre>?tag is used to represent pre-formatted text in HTML. The key difference between this tag and?{@code}?is that it supports line breaks and indentation.

/**
 * Returns a masked credit card number whose last 4 characters are shown while the rest is masked using the
 * {@code maskCharacter} parameter of type {@link Character}.
 * <br>
 * <pre>
 * StringUtils.maskCreditCardNumber("4111111111111111") = "XXXXXXXXXXXX1111"
 * </pre>
 *
 * @param creditCardNumber the credit card number to be masked.
 * @param maskCharacter    this {@code Character} masks the digits of the card.
 * @return the masked credit card number.
 * @since 1.4
 */
public static String maskCreditCardNumber(String creditCardNumber, Character maskCharacter) { ... }        

The code above generates the following HTML documentation:

7. Generate Documentation and See the Results for Yourself

The?maven-javadoc-plugin?plugin simplifies the process of generating?Javadocs?for the specified project.

Add the plugin to your?pom.xml?file.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.3.1</version>
            <configuration>
                <source>17</source>
                <encoding>UTF-8</encoding>
            </configuration>
        </plugin>
    </plugins>
</build>        

Run the command below to generate?Javadocs?in the?target/site?directory.

mvn javadoc:javadoc        

You can see the results by opening the generated?target/site/apidocs/index.html?file in your browser!

Thanks for reading. I hope this was helpful!

The example code is available on?GitHub.