What causes maven-javadoc-plugin goal test-javadoc to fail on errors but test-javadoc-no-fork just to have warnings

Question

I have a Maven project with maven-javadoc-plugin and JDK8. When I run mvn javadoc:test-javadoc then the plugin reports documentation-errors and stops, but when I run mvn javadoc:test-javadoc-no-fork the plugin runs successful and there's just some warnings.

The question is NOT how to fix or the documentation-errors. The plugin spotted real documentation-issues, that need to be fixed, so the reported errors of mvn javadoc:test-javadoc are the correct result.

The question is: Why does mvn javadoc:test-javadoc-no-fork not fail but handle the issues just as warning?

Background:

the project is a multi-module-project
Maven version: 3.3.9
maven-javadoc-plugin: 2.9.4 (the same behaviour occurs for 3.0.0-M1)
Java8

The sported problem in TracingServiceSpringTest has really a missing documentation for the thrown DatatypeConfigurationException

/** scenario: some text... **/
@Test
public void testImport() throws DatatypeConfigurationException {...

Output when running mvn javadoc:test-javadoc

[INFO]
[INFO] <<< maven-javadoc-plugin:2.10.4:test-javadoc (default-cli) < generate-test-sources @ agrovet-server <<<
[INFO]
[INFO] --- maven-javadoc-plugin:2.10.4:test-javadoc (default-cli) @ agrovet-server ---
[INFO]
...
3 errors
9 warnings
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] PROJECT ............................................ SUCCESS [  1.131 s]
[INFO] PROJECT :: Client .................................. SUCCESS [ 43.908 s]
[INFO] PROJECT :: Server .................................. FAILURE [ 44.774 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:36 min
[INFO] Finished at: 2017-09-23T21:33:33+02:00
[INFO] Final Memory: 96M/1573M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:test-javadoc (default-cli) on project PROJECT-server: An error has occurred in Test JavaDocs report generation:
[ERROR] Exit code: 1 - F:\workspaces\PROJECT\PROJECT-server\src\test\java\com\example\PROJECT\infrastructure\TracingServiceSpringTest.java:389: warning:
no @throws for javax.xml.datatype.DatatypeConfigurationException
[ERROR] public void testImport() throws DatatypeConfigurationException {
[ERROR] ^
...
[ERROR]
[ERROR] Command line was: "C:\Program Files\Java\jdk1.8.0_121\jre\..\bin\javadoc.exe" @options @packages
[ERROR]
[ERROR] Refer to the generated Javadoc files in 'F:\workspaces\PROJECT\PROJECT-server\target\site\testapidocs' dir.
[ERROR] -> [Help 1]
[ERROR]

...

Output when running mvn javadoc:test-javadoc-no-fork

8 warnings
[WARNING] Javadoc Warnings
[WARNING] F:\workspaces\PROJECT\PROJECT-server\src\test\java\com\example\PROJECT\infrastructure\TracingServiceSpringTest:389: warning: no @throws for javax.xml.datatype.DatatypeConfigurationException
[WARNING] public void testImport() throws DatatypeConfigurationException {
[WARNING] ^
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] PROJECT ............................................ SUCCESS [  0.454 s]
[INFO] PROJECT :: Client .................................. SUCCESS [  0.011 s]
[INFO] PROJECT :: Server .................................. SUCCESS [  6.763 [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

Relevant POM Parts, parent pom.xml (the complete pom is just too huge, but this is the only part that mentions the maven-javadoc-plugin :

<dependencyManagement>
    <dependencies>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.4</version>
        </plugin>
    </dependencies>
</dependencyManagement>
...
<reporting>
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <reportSets>
                <reportSet>
                    <reports>
                        <!-- 
                        javadoc-no-fork in order to prevent JavaDoc process from runing generate-source again
                        but this also requries that JavaDoc generation runs after compile: "mvn install site"
                        but not on a black project "mvn clean site"
                        -->
                        <report>javadoc-no-fork</report>
                        <report>test-javadoc-no-fork</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

Naman · Answer 1 · 2017-09-23T21:12:46.560

While trying to Generate Javadoc without duplicate execution of phase generate-sources. As of version 2.10 two new reports are defined, javadoc-no-fork and test-javadoc-no-fork will not trigger generate-sources or generate-test-sources phases again a second time.

When you use the option test-javadoc-no-fork the test-source generation is skipped and hence your build succeeds.

...generates the test Javadoc files for the project. It executes the standard Javadoc tool and supports the parameters used by the tool without forking the generate-test-sources phase again. Note that this goal does require generation of test sources before site generation, e.g. by invoking mvn clean deploy site.

on the other hand javadoc:test-javadoc the test-sources are compiled again and the error is logged.

generates the test Javadoc files for the project. It executes the standard Javadoc tool and supports the parameters used by the tool.

All of that with the <reportSets>

Multiple specifications of a set of reports, each having (possibly) different configuration. This is the reporting parallel to an <execution> in the build.

both of type no-fork, you can try and include test-javadoc as one of the reports in the <reportSet> to solve this.

But this issues are no compiler issues. The issues are just that the javadoc for an thrown exception is missing. -- And the javadoc tool is even when running `test-javadoc-no-fork` recognizing that problem (it generate a warning) but it does not stop the build. — Ralph, Sep 23 '17 at 20:50
@Ralph Ya probably I got you wrong initially. Trying to reproduce the same with one class each in my test and main, I was unable to get the failure for both the commands though. Also you can try and include `test-javadoc` as one of the reports and see if that helps. — Naman, Sep 23 '17 at 21:14

What causes maven-javadoc-plugin goal test-javadoc to fail on errors but test-javadoc-no-fork just to have warnings

1 Answers1