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>

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>

Answer 2

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>