How to make Maven build (goal site) fail on Javadoc warnings?

Question

I am building my Maven project with the goal site. There are Javadoc warnings in the output. In this case my Maven build has to fail. Is there a way to do that?

Here is the code snippet of my POM (I am using Maven 3.3):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.5</version>
    <configuration>
        <generateReports>true</generateReports>
    </configuration>
</plugin>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <configuration>
        <show>private</show>
        <failOnError>true</failOnError>
    </configuration>
</plugin>

Unicellular

Possibility to what? – Sforza

@Sforza possibility to make sure the build fails if the Javadoc encounters a problem.For example make the build on Jenkins fail so that the developers will get mail or something – Hissing

With JDK 8 is enabled doclint by default, but I suggest you are running on 7? – Sforza

Answer 1

The maven-javadoc-plugin cannot be configured to fail the build on warnings (only on errors with the parameter failOnError).

What you actually want is to use the maven-checkstyle plugin. This is the plugin that is responsible for checking that your code complies to a given predefined style. In this case, the style is that Javadoc must be present and must not have warnings. As such, configure the Checkstyle Plugin like this:

<plugin>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>2.17</version>
    <reportSets>
        <reportSet>
            <reports>
                <report>checkstyle</report>
            </reports>
        </reportSet>
    </reportSets>
    <configuration>
        <failsOnError>true</failsOnError>
        <configLocation>checkstyle.xml</configLocation>
    </configuration>
</plugin>

It references a checkstyle.xml (located relative to the project base directory). To check for Javadoc, you could have the following simple checkstyle configuration file:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Puppy Crawl//DTD Check Configuration 1.2//EN"
    "http://www.puppycrawl.com/dtds/configuration_1_2.dtd">

<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod"/>
        <module name="JavadocType"/>
        <module name="JavadocVariable"/>
        <module name="JavadocStyle"/>
    </module>
</module>

This will make the build fail for any Javadoc warnings. The Javadoc module are highly configurable; the sample configuration above will check for Javadoc and its correctness, on every method, every type and every variable.

As an example, you can restrict this to only public methods and public fields by setting the scope property to the JavadocMethod and JavadocVariable modules:

<module name="JavadocMethod">
    <property name="scope" value="public"/>
</module>
<module name="JavadocVariable">
    <property name="scope" value="public"/>
</module>

Ejaculation

Answer 2

Version 3.0.1 of the plugin added the failOnWarnings option, which is still supported as of the current 3.3.1 version. Your configuration should look like so:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.3.1</version>
  <executions>
    <execution>
      <id>attach-javadocs</id>
      <goals>
        <goal>jar</goal>
      </goals>
      <configuration>
        <failOnWarnings>true</failOnWarnings>
      </configuration>
    </execution>
  </executions>
</plugin>

Orpiment

Answer 3

If you use following snippet for maven-javadoc-plugin in build element then it will automatically fail even for warnings.

<executions>
    <execution>
        <id>attach-javadocs</id>
        <goals>
            <goal>jar</goal>
        </goals>
    </execution>
</executions>

Kinzer

This succeeds despite warnings for me. Maven 3.8.1, plugin version 3.3.1. – Orpiment

Answer 4

For this, you should use something like Sonarqube. Here is no reason to check it as part of CI. So, this is job for SonarQube but if you want to still check something in Jenkinse, you can try to use Text Finder Plugin for Jenkinse. Then you are able to set string containing any uniqeu part of java doc warning and then your build will be downgraded.

Sforza