Use maven JavaDoc with reasonable doclint parameters

Question

There is lots of information on how to switch off the JavaDoc lint feature in Java 8. Believe it or not, today I decided to use this functionality and fix my JavaDocs. However, in its standard configuration it is complaining about every possibly missing @param and @return. From what I see in the JavaDoc documentation at Java 8 javadoc technotes my option of choice is -Xdoclint:all,-missing. This should include all checks, but leave out complaints on missed documentation opportunities. The maven configuration looks like:

  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.10.4</version>
        <configuration>
          <additionalparam>-Xdoclint:all,-missing</additionalparam>
          <aggregate>false</aggregate>
        </configuration>
        <reportSets>
          <reportSet>
            <id>default</id>
            <reports>
              <report>javadoc</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>

However when running with mvn site I get the error:

[ERROR] Exit code: 1 - javadoc: error - invalid flag: -missing

I suspect that the parameter processing in maven is the problem, however, quoting didn't help.

Any ideas how to use this? Any alternative good practices to check JavaDoc in a reasonable way?

Answer 1

The syntax you expect to work (-Xdoclint:all,-missing) is correct. It will work fine with the native command line javadoc tool. Unfortunately the Maven JavaDoc Plugin seems to split an additional parameter into several parameters if a comma is used. This bug is documented in MJAVADOC-368.

To avoid your problem use the more verbose syntax which is described in @hasnae answer (-Xdoclint:all -Xdoclint:-missing).

Answer 2

The right syntax is:

-Xdoclint:all -Xdoclint:-missing