Java DocLint

1. Overview

There are so many reasons why using Javadoc is a good idea. For example, we can generate HTML from our Java code, traverse through their definitions, and discover various properties related to them.

Moreover, it facilitates communication among developers and improves maintainability. Java DocLint is a tool to analyze our Javadoc. It throws warnings and errors whenever it finds bad syntax.

In this tutorial, we focus on how we can use it. Later, we'll look at the problems it can create in certain situations, along with some guidelines on how we can avoid them.

2. How to Use DocLint

Suppose we have a class file named Sample.java:

/**
 * This sample file creates a class that
 * just displays sample string on standard output.
 *
 * @autho  Baeldung
 * @version 0.9
 * @since   2020-06-13 
 */
public class Sample {
    public static void main(String[] args) {
        // Prints Sample! on standard output.
        System.out.println("Sample!");
    }
}

Purposefully, There is a mistype here, the @author parameter is written @autho. Let's see what happens if we try to make Javadoc without DocLint:

As we can see from the console output, the Javadoc engine couldn't figure out the mistake in our documentation and did not return any errors or warnings.

To make Java DocLint return this type of warning, we have to execute the javadoc command with the –Xdoclint option. (we'll explain this in detail later):

As we can see in the output, it directly mentions the error in line 5 of our Java file:

Sample.java:5: error: unknown tag: autho
 * @autho  Baeldung
   ^

3. -Xdoclint

The -Xdoclint parameter has three options for different purposes. We'll take a quick look at each one.

3.1. none

The none option disables the -Xdoclint option:

javadoc -Xdoclint:none Sample.java

3.2. group

This option is useful when we want to apply certain checks related to certain groups, for example:

javadoc -Xdoclint:syntax Sample.java

There are several types of group variables:

• accessibility – checks for the issues to be detected by an accessibility checker (for example, no caption or summary attributes specified in a table tag)
• html – detects high-level HTML issues, like putting block elements inside inline elements or not closing elements that require an end tag
• missing – checks for missing Javadoc comments or tags (for example, a missing comment or class, or a missing @return tag or similar tag on a method)
• reference – checks for issues relating to the references to Java API elements from Javadoc tags (for example, item not found in @see, or a bad name after @param)
• syntax – checks for low-level issues like unescaped angle brackets (< and >) and ampersands (&) and invalid Javadoc tags

It's possible to apply multiple groups at once:

javadoc -Xdoclint:html,syntax,accessibility Sample.java

3.3. all

This option enables all groups at once, but what if we want to exclude some of them?

We could use the -group syntax:

javadoc -Xdoclint:all,-missing

4. How to Disable DocLint

Since Java DocLint didn't exist before Java 8, this can create unwanted headaches, especially in old third-party libraries.

We've already seen the none option with the javadoc command in a previous section In addition, there's an option to disable DocLint from build systems like Maven, Gradle, Ant. We'll see these in the next few subsections.

4.1. Maven

With maven-javadoc-plugin, starting with version 3.0.0, a new doclint configuration has been added. Let's see how to configure it to disable DocLint:

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.1.1</version>
        <configuration>
            <doclint>none</doclint> <!-- Turn off all checks -->
        </configuration>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

But generally, it's not recommended to use the none option because it skips all types of checks. We should use <doclint>all,-missing</doclint> instead.

When using earlier versions (before v3.0.0), we need to use a different setting:

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

4.2. Gradle

We can deactivate DocLint in Gradle projects with a simple script:

if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
        tasks.withType(Javadoc) {
            options.addStringOption('Xdoclint:none', '-quiet')
        }
    }
}

Unfortunately, Gradle doesn't support additionalparam as Maven does in the example above, so we need to do it manually.

4.3. Ant

Ant uses additionalparam as Maven does, so we can set -Xdoclint:none as demonstrated above.

5. Conclusion

In this article, we looked at various ways of using Java DocLint. It can help us when we want to have a clean, error-prone Javadoc.

For additional in-depth information, it's a good idea to have a look at the official documentation.