Is there a workaround for maven-javadoc-plugin bug MJAVADOC-414?

Question

While using maven-javadoc-plugin to generate test Javadoc I suddenly got multiple errors stating that the Javadoc plugin was unable to find any classes from my main codebase. While running the test-javadoc goal the classpath contained only classes within the src/test folder; no classes from src/main were visible to the plugin.

This bug occurs on maven-javadoc-plugin versions 2.10, 2.10.1 and 2.10.2. This error is the officially recognized bug MJAVADOC-414, and you can view the bug report here. The official bug report lists a workaround that involves downgrading the plugin to version 2.9.1, which I have confirmed is a successful workaround for the errors. It is also worth noting that the bug is currently listed as fixed, and should be eliminated upon the next release of maven-javadoc-plugin, which is likely version 2.11 2.10.3.

However, I am trying to find a workaround to MJAVADOC-414 that does not involve the overkill of downgrading 3 release versions. Does anyone know of a workaround that will successfully eliminate the erroneous error messages about missing class references in an alternative way that doesn't involve downgrading?

Answer 1

A potential non-downgrade workaround that I am currently using successfully with maven-javadoc-plugin 2.10.2 involves adding a small configuration to all test related executions of the plugin, including the following goals: test-javadoc, test-javadoc-nofork, test-aggregate, test-jar, test-aggregate-jar, test-fix and test-resource-bundle.

Once you have identified an execution targetting a listed goal, you simply add the following configuration to that execution:

<!-- Additional Dependencies workaround for MJAVADOC-414 -->
<additionalDependencies>
    <additionalDependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>${project.artifactId}</artifactId>
        <version>${project.version}</version>
    </additionalDependency>
</additionalDependencies>

This workaround uses the additionalDependencies tag to add a dependency to the classpath during the plugin's execution. The dependency added is defined using the project variables for groupId, artifactId and version. In effect, we are adding the project defined by the current POM into the classpath of the maven-javadoc-plugin test execution.

Defining the dependency via relative variables makes this solution safe for both single POM and multiple POM projects. This solution can also successfully be used with a pluginManagement declaration. If you accidentally add this solution to non test phase related executions it should be harmless, but it will likely be a duplication and may increase execution time.