3

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?

Emily Mabrey
  • 1,528
  • 1
  • 12
  • 29
  • 1
    This is a good Q&A, +1 for both. But consider revising your "block of text" format. Use paragraphs and white space to make it more legible. – Boris the Spider Apr 05 '15 at 11:43
  • Thanks for the vote and advice; I updated both the Q and A with paragraphs. – Emily Mabrey Apr 05 '15 at 11:49
  • Do you have the chance to test a SNAPSHOT version of maven-javadoc-plugin version 2.10.3 ? So we can be sure that the problem is solved? So i could start a release next week... – khmarbaise Apr 05 '15 at 13:32
  • @khmarbaise I was able to acquire a copy of maven-javadoc-plugin `2.11-SNAPSHOT` by using `http://repository.apache.org/snapshots` as a plugin repository. The SNAPSHOT version successfully generated test Javadoc only with my already posted workaround. Without my workaround, `2.11-SNAPSHOT` generated the same errors that `2.10` release versions generate. Either the bug is incorrectly marked fixed, or the patch has not been rolled into the SNAPSHOT build. – Emily Mabrey Apr 05 '15 at 13:45
  • First thanks for your help. As i said. `2.10.3-SNAPSHOT`. I have deployed the current state of trunk as 2.10.3-SNAPSHOT just to be sure to the snapshot repository. It would be nice if you could recheck... – khmarbaise Apr 05 '15 at 20:22
  • @khmarbaise My mistake- I just assumed incorrectly. I repeated the testing of the workaround with `2.10.3-SNAPSHOT`. The workaround had no effect on the output of this version, and I was unable to reproduce the bug for version `2.10.3-SNAPSHOT`. I believe that the bug has been successfully fixed. – Emily Mabrey Apr 07 '15 at 03:51
  • Hi Cool thanks for your feedback. So i can start a new release within the next days. – khmarbaise Apr 07 '15 at 06:39
  • @khmarbaise No problem. How would I go about contributing to the javadoc plugin if I wanted to bugfix/submit patches? Is it open to anyone or only approved submitters? – Emily Mabrey Apr 08 '15 at 07:22
  • Patches and helps is always welcome and appriciated. You can simply add those patches to the issue in jira (https://issues.apache.org/jira/browse/MJAVADOC) and if you delivered enought well working patches you will be elected to become a committer. See http://maven.apache.org/guides/development/guide-helping.html You can express your wished to work on something on the developers list... – khmarbaise Apr 08 '15 at 08:22
  • So i have started the release vote for the new version which contains this fix. http://mail-archives.apache.org/mod_mbox/maven-dev/201504.mbox/%3C55276E22.2070802%40gmx.de%3E This will take 3-4 days to go through. – khmarbaise Apr 10 '15 at 09:49
  • 1
    So the new release is officially announced. – khmarbaise Apr 16 '15 at 17:34

1 Answers1

2

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.

Emily Mabrey
  • 1,528
  • 1
  • 12
  • 29