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

Question

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 <[email protected]> 
 */

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.

Iowa

This blog shows how this can be turned off: blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html – Carcinomatosis

You can use -Xdoclint even with javac to tell it to check the docs while compiling… – Ditheism

@HimanshuBhardwaj. Thanks for linking to Stephen Colebourne's blog. The best piece I've read on this subject so far! – Iowa

Additionally one of "errors" is erroneous as well: 'bad usage of '>' -- this is wrong, '>' is perfectly acceptable in XML, except for the specific sequence of ']]>' which is not accepted (one of chars must be escaped). Only '<' must be escaped, '>' does have mnemonic (gt) for convenience but its use is completely optional. – Sweven

I wonder what's with the HTML 4 compliance instead of HTML 5. Personally, I'd prefer a simple markup language since I have to read the source code and not just the pretty output; and at least for me the human-readability of HTML is debatable. – Maddocks

@ThiagoPorciúncula. I believe the question here is a bit broader than that: "This question exist to collect proposals on what to do about it. What is the best approach?". Certainly just turning off DocLint is one solution but perhaps there are others. For example I'm surprised nobody has come up with tools that would easily assist the developer in the process of fixing those (potentially) thousands of source code files. The question you point to only deals with the issue of incomplete tags but the question here is broader than that. – Iowa

@ThiagoPorciúncula .. for example this question documents cases where there's no syntax error in the JavaDoc, nothing is incomplete from an HTML point of view, yet DocLint will still refuse it (the <table> example). – Iowa

@Iowa I see your point. Since all the answers (including mine) are like duplicate answers from the other question, I felt the question itself was also a duplicate. But you're probably right, I'll remove my flag. – Caster

@Sweven I strongly second your comment: not only does the HTML standard as I understand it fully permit the use of '>' in HTML text, this error breaks JavaDoc when it attempts to process output from the JAX-B compiler. – Hemp

@user114622. The HTML standard says authors should use "&gt;" (ASCII decimal 62) in text instead of ">". Although this is not stated as a MUST I believe it is acceptable that Javadoc will enforce it. – Iowa

Stackoverflow documentation would be a perfect place for this doc – Encyclopedic

You can actually disable doclint when running maven, see this answer. – Venipuncture

Related, escaping special characters, e.g. '<': #2291257 – Admissive

Answer 1

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!

Emarie

I'll accept this as the most likely solution that most of us will implement. I like the <activation> part. But I wish someone would come up with a tool that could go through those many source files and aid the developer in fixing the errors ... rather than just turning off DocLint. – Iowa

Beware using this solution if you rely on another profile being active by default at the same time (using activeByDefault=true). – Deviation

@peterh: There is no meaning of documenting fully everything, that is a useless duplicated work, by clean code principles it is recommended to document only what is not obvious, and the public API. – Subsequence

This does not work with maven-javadoc-plugin version 3.0.0. I had to go back to version 3.0.0-M1 for making -Xdoclint:none work. – Superannuated

@MehradSadegh For maven-javadoc-plugin version 3.0.0 just replace <additionalparam>-Xdoclint:none</additionalparam> by <doclint>none</doclint> – Noe

As off maven-javadoc-plugin version 3.0.0 you can use additionalJOption property to pass options to javadoc, it will be <additionalJOption>-Xdoclint:none</additionalJOption> property in this case. – Rager

Yes, Adding JDK 8 related profile & setting <doclint>none</doclint> resolves the issue. It generates javadoc jar same as it was generating in JDK 7. Thanks. – Flageolet

<doclint>none</doclint> finally helped after searching stackoverflows for a while.. thanks!!! – Bootstrap

Answer 2

If you are using the maven javadoc plugin, you can use the failOnError option to prevent it from stopping if it finds any html errors:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

Or you can deactivate the strict html options completely with:

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

For more info.

Corrales

Hmm. The problem with these solutions is that if you think of it with JDK8 Javadoc you would want not to fail on errors whereas with JDK7 Javadoc you do. So for this reason I like best the -Xdoclint option. The hope is it will be silently ignored if executed with a JDK7 Javadoc ? – Iowa

You could apply the option conditionally via a maven profile keyed on the Java version…? – Enchanter

Nope, with JDK7 it fail with javadoc: error - invalid flag: -Xdoclint:none (nice job Oracle). – Payson

Answer 3

Note that for the error no summary or caption for table, using <table summary=""> won't work anymore. If that's your situation, add a <caption> element to your table, like this:

<table>
    <caption>Examples</caption>
    ...
</table>

Hope this helps someone out there. It took me a while until I found this out.

Chauchaucer

What version of the JDK? For sure the <table summary=""> trick still works on JDK8. (just tested on jdk1.8.0_201) – Iowa

@Iowa I used jdk 11. – Chauchaucer

This is the up-to-date answer. summary="..." attribute is not supported with HTML5 (the default output for JDK 11 javadoc) any more. It is also supported in JDK 8. – Cerulean

Answer 4

Since version 3.0.0 of maven-javadoc-plugin the doclint is configured via the dedicated XML tag

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>

Theomachy

Answer 5

I like @ThiagoPorciúncula's solution but it didn't quite go far enough for me.

I typically already have javadoc plugin additionalparam set which were not being overridden by the profile. Because of this I had to:

• Set a disableDoclint property to be empty by default.
• If in java >= 8, set the disableDoclint property to be -Xdoclint:none
• The use ${disableDoclint} in the additionalparam section of the maven-javadoc-plugin.

This seems to work well albeit verbose.

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

Then down below I could use the optional ${disableDoclint} variable in the additionalparam section that I had already defined.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
    </configuration>
</plugin>

This works under java 8 but doesn't cause syntax errors under java 7. Woo hoo!

Alcibiades