Automatic verification of JavaDoc with Maven

Question

During refactoring it happens frequently that JavaDoc gets out-of-date. It describes method arguments which are not present any more or some new ones are missing, to give examples.

It would be fine, if there is a Maven-plugin which automatically checks the existing JavaDoc and stops the build if there are some kind of "JavaDoc-violations". I've seen the Maven-JavaDoc-Plugin and maven-doccheck, but both seem only to be able fix existing JavaDoc automatically in case of violations instead of bailing some error or warning.

Does anyone know how if there is some Maven-plugin like this and how to archive this?

Answer 1

As far as I know this is currently not possible with the maven-javadoc-plugin. There is the javadoc:fix mojo for the JavaDoc plugin, but this automatically fixes problems.

I recently created a JIRA entry for this problem: MJAVADOC-374 (which is acutally a duplicate of MJAVADOC-314).

Update: You can use Checkstyle to verify correct JavaDoc. The configuration options are described here. Use the maven-checkstyle-plugin and the check-Mojo to integrate this into your maven build.

An example maven configuration could look like this:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>2.15</version>
        <configuration>
          <logViolationsToConsole>true</logViolationsToConsole>
          <checkstyleRules>
            <module name="JavadocMethod">
              <property name="scope" value="public"/>
              <property name="allowUndeclaredRTE" value="true"/>
              <property name="allowMissingParamTags" value="false"/>
            </module>
          </checkstyleRules>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>