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 o

Answer 1

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 theadditionalparamsection of themaven-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!

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.

Answer 3

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>

Answer 4

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.

Answer 5

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!