Skip to content
Advertisement

How to work around the stricter Java 8 Javadoc when using Maven

You’ll quickly realize that JDK8 is a lot more strict (by default) when it comes to Javadoc. (link – see last bullet point)

If you never generate any Javadoc then of course you’ll not experience any problems but things like Maven release process and possibly your CI builds will suddenly fail where they worked just fine with JDK7. Anything that checks the exit value of the Javadoc tool will now fail. JDK8 Javadoc is probably also more verbose in terms of warnings compared to JDK7 but that’s not the scope here. We are talking about errors!

This question exist to collect proposals on what to do about it. What is the best approach ? Should these errors be fixed once and for all in the source code files? If you have a huge code base this might be a lot of work. What other options exist ?

You are also welcome to comment with stories of what now fails that would previously pass.

Horror stories of what now fails

wsimport tools

wsimport tool is a code generator for creating web service consumers. It is included in the JDK. Even if you use the wsimport tool from JDK8 it will nevertheless produce source code that cannot be compiled with the javadoc compiler from JDK8.

@author tag

I’m opening up source code files 3-4 years old and see this:

/**
 * My very best class
 * @author John <john.doe@mine.com> 
 */

This now fails because of the < character. Strictly speaking this is justified, but not very forgiving.

HTML tables

HTML Tables in your Javadoc? Consider this valid HTML:

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

This now fails with error message no summary or caption for table. One quick fix is to do like this:

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

but why this has to be a stop-the-world error from Javadoc tool beats me??

Things that now fail for more obvious reasons

  1. Invalid links, e.g. {@link notexist}
  2. Malformed HTML, e.g. always returns <code>true<code> if ...

UPDATE

Links:

Excellent blog on the subject by Stephen Colebourne.

Advertisement

Answer

For now, the easiest way I know to work around the stricter Java 8 Javadoc when using Maven is deactivating it.

Since the parameter -Xdoclint:none only exists in Java 8, defining this parameter breaks the build for any other Java. To prevent this, we can create a profile that will be active only for Java 8, making sure our solution works regardless of the Java version.

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

Just add that to your POM and you’re good to go.

For maven-javadoc-plugin 3.0.0 users:

Replace

<additionalparam>-Xdoclint:none</additionalparam>

by

<doclint>none</doclint>

Thanks @banterCZ!

Advertisement