Cannot link to assertj-core JavaDoc due to JPMS (related to JDK-8240169)

Summary

The JavaDocs for AssertJ appear to be being built under Java 8, which means the Java-9 module-info.class descriptor is not being taken into account, resulting in a JavaDoc being generated that behaves as if it were defined in the unnamed module (i.e. with no module name prefix on the path).

When linking another project to these JavaDocs for a JPMS-enabled project, maven-javadoc-plugin appears to be unable to link correctly.

Example

Under Maven 3.8.5, maven-javadoc-plugin 3.3.2, assertj-core 3.22.0, java-release.version 11:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>${maven-javadoc-plugin.version}</version>
  
  <configuration>
    <additionalOptions>
      <option>--override-methods=detail</option>
      <option>-version</option>
    </additionalOptions>
    <source>${java-release.version}</source>
    <links>
      <link>https://javadoc.io/doc/org.assertj/assertj-core/${assertj.version}</link>
    </links>
  </configuration>
  
  <executions>
    <execution>
      <id>default-javadoc</id>
      <phase>package</phase>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Running under JDK 11, JDK 12, JDK 13, and JDK 14; Maven will fail with the following error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.3.2:jar (default-javadoc) on project java-compiler-testing: MavenReportException: Error while generating Javadoc: 
[ERROR] Exit code: 1 - javadoc: error - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[ERROR] 
[ERROR] Command line was: /opt/hostedtoolcache/Java_Zulu_jdk/12.0.2-3/x64/bin/javadoc @options @packages @argfile
[ERROR] 
[ERROR] Refer to the generated Javadoc files in '/home/runner/work/java-compiler-testing/java-compiler-testing/java-compiler-testing/target/apidocs' dir.
[ERROR] 
[ERROR] -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

Under JDK 15 and above, this just spams a large number of warnings instead:

 23 warnings
[WARNING] Javadoc Warnings
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.
[WARNING] javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.22.0/ are in the unnamed module.

This effectively prevents a project from being able to depend and extend parts of assertj while still providing valid documentation. This applies to both the hosted JavaDoc you link to from the assertj page, and the generated JavaDoc on javadoc.io.

For example, if I had a library with this API defined in it (not correct code, but you get the idea):

module org.example.me.compilerassertions {
  requires org.assertj.core;
  exports org.example.me;
}

// extending AbstractObjectAssert should link the inherited methods from the assertj-core javadocs
class CompilerAssertions extends AbstractObjectAssert<CompilerAssertions, Compilation> {
  private Compilation compilation;
  
  ...
  
  /**
   * Assert compilation succeeded.
   */
  public CompilerAssertions isSuccessful() {
    assertThat(compilation.isSuccess())
        .withFailMessage("Expected compilation to succeed, but it failed")
        .isTrue();
    return myself;
  }
}

---

Possible solution (?)

One possible solution may be to run JavaDoc from Java 9 or newer to allow module descriptors to be created (assuming the task is run from a Java 8 JVM). This would require anyone linking to these docs from JDK 8 to use a modified path. Hopefully most projects that are actively maintained should be targeting JDK 11 and newer now (even if they still support Java 8 as a minimum), meaning they may also come across this issue if they are in the same scenario. Java 8-only projects may have linking issues from JavaDoc, but this will eventually be an issue anyway once Java 8 extended support ends.

[ascopes]

Might have to be in the morning; will set myself a reminder to take a look.

Most recent one I can spot in the wild is at https://github.com/ascopes/jct/runs/6440094969?check_suite_focus=true#step:4:84 which is a Maven project at https://github.com/ascopes/jct. Haven’t had a more recent build since I have been working on a rewrite on a side branch that broke a lot of stuff, but I believe there is a cronjob to rerun that at midnight UTC if a more recent run is needed.

It isn’t exactly “minimal” so I will see what I can do in the morning, and get back to you!

[ascopes]

Cool, if you need any help verifying the issue with an existing project, feel free to shout and I can give it a try!