JDK-8212233 : javadoc fails on jdk12 with "The code being documented uses modules but the packages defined in $URL are in the unnamed module."
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11,12
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-10-16
  • Updated: 2020-02-27
  • Resolved: 2019-01-15
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 11 JDK 12 JDK 13
11.0.3Fixed 12 b28Fixed 13Fixed
Related Reports
Relates :  
JDK-8240169 - javadoc fails to link to docs with non-matching modularity
Relates :  
JDK-8216497 - javadoc should auto-link to platform classes
Relates :  
JDK-8205593 - Javadoc -link makes broken links if module name matches package name
Description
UPDATE FOR THOSE WHO GOOGLED THIS BUG: 
If the project uses source/target 8, adding <source>8</source> in javadoc configuration should make the project buildable on jdk {11, 12, 13}:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <source>8</source>
    </configuration>
     ...
  </plugin>

------

Take the simple Maven project with latest plugin dependencies (for example, http://cr.openjdk.java.net/~shade/8212233/javadoc-bug.tar.gz ), and run with JDK 11 and then with current JDK 12 EA. JDK 11 build would succeed (UPD: it would with JDK 11 GA, but not with later updates), and JDK 12 EA would fail on javadoc generation, which looks like a regression. Or maybe the Maven plugins need to do some new incantation to get it right?



I see projects started to disable Javadoc on 12 because of this:
  https://www.google.de/search?q=%22The+code+being+documented+uses+modules+but+the+packages+defined+in%22

$ export JAVA_HOME=~/Install/jdk11-oracle-ga/
$ export PATH=$JAVA_HOME/bin:$PATH
$ java -version
openjdk version "11" 2018-09-25
OpenJDK Runtime Environment 18.9 (build 11+28)
OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode)

$ mvn clean install
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.345 s
[INFO] Finished at: 2018-10-16T11:37:09+02:00
[INFO] Final Memory: 19M/176M
[INFO] ------------------------------------------------------------------------

$ export JAVA_HOME=~/Install/jdk12-oracle-b15/
$ export PATH=$JAVA_HOME/bin:$PATH
$ java -version
openjdk version "12-ea" 2019-03-19
OpenJDK Runtime Environment (build 12-ea+15)
OpenJDK 64-Bit Server VM (build 12-ea+15, mixed mode, sharing)

$ mvn clean install
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.415 s
[INFO] Finished at: 2018-10-16T11:38:35+02:00
[INFO] Final Memory: 25M/200M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.0.1:jar (attach-javadoc) on project bug: MavenReportException: Error while generating Javadoc: 
[ERROR] Exit code: 1 - javadoc: error - The code being documented uses modules but the packages defined in https://docs.oracle.com/javase/8/docs/api/ are in the unnamed module.
[ERROR]
Comments
Fix Request: Backport did not apply cleanly, but merge seemed straight forward. https://cr.openjdk.java.net/~martin/webrevs/jdk11/JDK-8212233-backport/ Our fix for this has been "soaking" in a Google-internal branch of jdk11u for a while without ill effects. Confirmed that the regression test PASSES on jdk11 with patch, FAILS without. Although it does not address all maven+javadoc problems, seems worth backporting.
19-02-2019
Hello all, we're being affected by this on the Hibernate ORM build. Adding {{--source 8}} on Java 12 (build 12+32) is working fine, but it's an open problem on Java 11. Earlier versions of Java 11 would build without such problems, while on version 11.0.2 the build fails - however {{--source 8}} doesn't seem to be an accepted parameter on that version of javadoc. Also with existing build tools (we use both Maven and Gradle) it is very messy to add a switch for certain micro versions of the JVM only, so I would suggest if this build error could be reverted within the Java 11 branch? A warning would suffice? Thanks
18-02-2019
Don't know much about maven, but ... possibly relevant: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=919875 https://github.com/vladak/OpenGrok/commit/3a912936bfb77fd417394c215a93fdf34edca39f There's a serious problem in the ecosystem with javadoc + maven + jdk 11
12-02-2019
The workaround seems to not help in some cases: The JAX-RS pom.xml uses Maven JavaDoc plugin 3.0.1 and explicitly configures <source>8</source> to workaround this issue when compiling for Java 8 on JDK 11, but this leads to the following error: "option --module-path not allowed with target 1.8". What can we do? Shall we simply wait for Maven JavaDoc plugin 3.1.0 or is there another trick we could do meanwhile (other than not using JDK 11)?
05-02-2019
Like Aleksey, we're seeing this bug pop up only with the latest jdk11u. Seems like it should be backported to jdk11u, but the patch does not apply cleanly. Here's an attempt that seems to work: https://cr.openjdk.java.net/~martin/webrevs/jdk11/JDK-8212233-backport/
31-01-2019
The current pom-file is still missing a language specific segment for values that are used by multiple plugins, such as source and release. The fastest solution would be to reuse the (global) properties maven.compiler.source and maven.compiler.release. Will probably be solved as part of https://issues.apache.org/jira/browse/MJAVADOC-562
18-01-2019
I see people come to this issue looking for the fix for their build failures. Updated the description with the workaround^W fix for source/target 8.
18-01-2019
and the workaround is probably the right thing to do anyway as the project is compiled against 8 so presumably the project's javadoc would be better linking to the Java SE 8 docs rather than the version of the JDK used to run the javadoc tool.
18-01-2019
[~rfscholte] Re: Jonathan, the list of detectJavaApiLinks is shown at https://github.com/apache/maven-javadoc-plugin/blob/master/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L1761 , can I assume that from now on it will follow the structure of Java 11? The docs team assure me that 12 will be similar to 11.
10-01-2019
I have a fix, and a regression test. I'll start a review; this should be reasonable for 12.
10-01-2019
[~rfscholte] For options that directly relate to the module system, (--module-path, --class-path, --add-modules, --limit-modules, etc) you're pretty much guaranteed 1-1 fidelity between javac and javadoc, because javadoc delegates these options to an internal copy of javac. The intent is that the options should generally behave the same as in the runtime, although the implementation is obviously way different in that case. There are some inherent differences ... e.g. javac allows source code on the patch module path, but that sort of detail should not be unexpected. The challenge, which is what we're seeing in this bug, is making sure that javadoc-only options, like -link and -linkoffline, are in line with the general model. One complication that needs to be taken into account is that during compilation, a component "evolves". A set of source files can be compiled into a (non-modular) set of class files, and even corresponding API docs, but then the class files can be converted into a modular jar, using the jar tool and setting a module name ... without necessarily changing/updating the API docs.
09-01-2019
[~jjg] That was the answer I was hoping for: the arguments should be in line with each other. All our maven-plugins that are aware of modulepath and classpath use the same library for calculating those arguments, based on the same principal.
09-01-2019
[~rfscholte] I think you can assume the pattern of API links will follow the structure of 11 .... until you see/read discussion that it might change again. I'll be looking in detail at the use case and command lines here, but the general assumption is that there should a strong correlation between the javadoc command and the corresponding javac command. Obviously there are notable differences (javadoc does not support/require -target; javadoc does require -link or -linkoffline, etc) but options related to configuring the module system should be the same for both tools ... implying that unnecessary differences are potentially bugs or at least areas for improvement. With respect to this issue, my going-in assumption is that if the module path, class path, automatic modules, etc have been set up for javadoc in a way that mirrors the equivalent configuration for javac, then it must be possible to set up links for API for the modules (and unnamed module) in a reasonably obvious manner. That may not be as detailed as you want to see at this point, but I hope it does outline the constraints for the design for a resolution.
09-01-2019
Jonathan, the list of detectJavaApiLinks is shown at https://github.com/apache/maven-javadoc-plugin/blob/master/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L1761 , can I assume that from now on it will follow the structure of Java 11? And I'm still missing the confirmation that the usecase (and constructed commandline) with the automatic module is valid and must be solved in the javadoc tool, otherwise I need to know which arguments I need to pass instead. Just to be clear, it is not just about the error, but also about the removed links to the classes of the automatic module.
09-01-2019
[~rfscholte] w.r.t the detectJavaApiLink plugin and the need to update the list every so often ... the locations should follow a pattern, except when they don't, so (if it doesn't already) the plugin could be such that it only needs to be updated when the pattern for the location changes, which ideally should be less often ;-)
09-01-2019
From reading the comments, it may be that we just have to finesse how/when the error message is generated.
09-01-2019
Robert - thanks for the update. Using Aleksey's example, I can confirm changing the maven-javadoc-plugin configuration to: <configuration> <source>8</source> </configuration> does result in javadoc being executed with `-source 8` and the javadoc to be generated. For the Guava example then guava-27.0.1-jre.jar on the module path means we have an automatic module. Jon can confirm but I think this means javadoc may have to support linking to the javadoc of an unnamed module.
07-01-2019
Hi Alan, regarding your questions: 1. For the link to the Java SE 8 API the maven-javadoc-plugin has uses the parameter https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectJavaApiLink . The plugins holds alist of links for most Java versions (downside is that this list should be extended every 6 months). There's a parameter for source, namely https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#source which you need to set; I'm not aware of the target-option for javadoc. 2. The latter: guava-27.0.1-jre.jar is put on the modulepath ( for both javac and javadoc )
07-01-2019
Two questions for Robert: 1. In Aleksey's example, the project is compiled with -source 8/-target 8 but there aren't any equivalent options in the maven-javadoc-plugin configuration. How does the maven-javadoc-plugin know to link to to the Java SE 8 API docs, is it picking up maven-compiler-plugin configuration? If so, I'm wondering if it invokes javadoc with -source/-target 8 or not. 2. In Gili's example is guava-27.0.1-jre.jar deployed on the class path or is it deployed on the module path as an automatic module?
07-01-2019
I've attached a zip-file with the stripped commandline arguments (Windows based, so you might need to adjust file separators). What surprises me, is that the apidocs are generated even though there's an error.
06-01-2019
How are you compiling and running this set of code? In general, code in a module cannot refer to code on the class path. The only way this might work would be to use `--add-reads myModule=ALL-UNNAMED`. If that works at compile-time and run-time, then by extension it is reasonable to expect that it should work at javadoc time. I'm not saying that it does today; I'm saying that we could look at adding support for that option in an upcoming release.
06-01-2019
The issue we're facing is a project which has a module descriptor and which requires a dependency called {{guava-27.0.1-jre.jar}}. This is a jar containing a MANIFEST file containing the entry {{Automatic-Module-Name: com.google.common}}. We want to link using {noformat} -link 'https://google.github.io/guava/releases/27.0.1-jre/api/docs' {noformat} These api docs are classic docs, no modular info. This used to work with JDK 9, 10 and 11, but seems to be broken with the latest JDK 12
06-01-2019
It would help to understand the conceptual use-case here, and to get javadoc out of the loop by considering java instead. The general model here is that -- non-modular code should be able to refer to code on the source/classpath and to exported packages from modules. -- modular code refers to code in other modules, but generally not code on the source/classpath That is the intent of the model supported by javac and javadoc. If you can compile the code (with javac) the general intent is that it should be possible to generate API docs with javadoc.
05-01-2019
Maven folks are wondering how to fix this here: https://issues.apache.org/jira/browse/MJAVADOC-555 Setting source/target, as suggested here, did not seem to help. Reopening.
05-01-2019
Simple workaround is to throw the entire javadoc under the bus by overriding the external links completely: <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.0.1</version> <executions> <execution> <id>attach-javadoc</id> <phase>verify</phase> <goals> <goal>jar</goal> </goals> </execution> </executions> <configuration> <javaApiLinks> <property> <name>foo</name> <value>bar</value> </property> </javaApiLinks> </configuration> </plugin> Might be better to point to 11 apidocs, but the project is "supposed" to be 8-only, as we set source/target to 8 for compiler.
27-11-2018
I don't think maven-javadoc-plugin has a way to pass "--source" or "--release" to javadoc tool. Looked at plugin documentation, as well as grepped the source. The options block Jonathan pasted above has no mention of the source/release. POM sets 1.8 to maven-compiler-plugin, but that obviously has no effect on maven-javadoc-plugin. I guess the only viable option at this point is keeping JDK 11 GA build around to compile with.
27-11-2018
For the record, this started to happen with JDK 11.0.1 as well. JDK 11 GA is still fine.
27-11-2018
This looks like a Maven issue. Here are the relevant files: $ more ./target/apidocs/{options,packages} :::::::::::::: ./target/apidocs/options :::::::::::::: -encoding 'UTF-8' -protected -sourcepath '/w/jjg/work/jdk.ref/play/shipilev/javadoc-bug/src/main/java:/w/jjg/work/jdk.ref/play/shipilev/javadoc-bug/target/generated-sources/annotations' -author -bottom 'Copyright &#169; 2018. All rights reserved.' -charset 'UTF-8' -d '/w/jjg/work/jdk.ref/play/shipilev/javadoc-bug/target/apidocs' -docencoding 'UTF-8' -doctitle 'bug 1.0-SNAPSHOT API' -linkoffline 'https://docs.oracle.com/javase/8/docs/api' '/w/jjg/work/jdk.ref/play/shipilev/javadoc-bug/target/javadoc-bundle-options' -use -version -windowtitle 'bug 1.0-SNAPSHOT API' :::::::::::::: ./target/apidocs/packages :::::::::::::: org.openjdk.javadoc Note the reference to https://docs.oracle.com/javase/8/docs/api Note that this command line is incorrect for any JDK >=9 using source version >= 9 ... and is not just a result of the recent compatibility check added in JDK-8205593. If the program being documented used any recent API, the documentation for that API would not have been found at that URL.
27-11-2018
The bug report has the example linked, can you try this on JDK 12? http://cr.openjdk.java.net/~shade/8212233/javadoc-bug.tar.gz Pretty sure running it with "mvn clean install -X" would tell all the diagnostics, including command lines it used to invoke javadoc.
09-11-2018
Need (a bit) more info. In particular, it would help to see the command line obtained by expanding the options and packages files. This is probably related to JDK-8205593: Javadoc -link makes broken links if module name matches package name What's notable is this line in the output: The code being documented uses modules but the packages defined in https://docs.oracle.com/javase/8/docs/api/ are in the unnamed module What this is saying is that you're running javadoc with either the defauilt source/target/release or with them set to 9 or greater ... i.e. a modular compilation environment. But you're trying to link against JDK 8 API, as stated in the error message. JDK-8205593 was aboput checking the consistency of the compilation environment against the external API environment. That would seem to make this "Not An Issue / User Error". There are two ways to fix this. 1. If this really is a JDK8-era program, use the javadoc option --source 8 or --release 8. 2. If this is meant to be a demo for using javdoc on a recent JDK, change the -link option to point to the Java SE API directory of the desired release.
09-11-2018