JDK-8240169 : javadoc fails to link to docs with non-matching modularity
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11,15
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2020-02-27
  • Updated: 2020-08-03
  • Resolved: 2020-04-08
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 15
11.0.9-oracleFixed 15 b18Fixed
Related Reports
Duplicate :  
JDK-8240194 - Improve/fix javadoc support for linking to docs for automatic modules
Duplicate :  
JDK-8241640 - Javadoc error if unnamed module depends on named module
Duplicate :  
JDK-8240232 - Javadoc fails to link to modular jars from non-modular project
Relates :  
JDK-8212233 - javadoc fails on jdk12 with "The code being documented uses modules but the packages defined in $URL are in the unnamed module."
Relates :  
JDK-8250954 - Avoid multiple warnings for external docs with mismatching modularity
Relates :  
JDK-8241640 - Javadoc error if unnamed module depends on named module
Relates :  
JDK-8240232 - Javadoc fails to link to modular jars from non-modular project
Relates :  
JDK-8240194 - Improve/fix javadoc support for linking to docs for automatic modules
Description
Note: this bug was originally filed for modular jars linking to non-modular documentation. It was updated to include the inverse case as well.

The javadoc tool fails with "The code being documented uses modules but the packages defined in $URL are in the unnamed module." when it consumes Java modules which published their API documentation in a non-modular fashion.

"javadoc ... -link https://ota4j-team.github.io/opentest4j/docs/1.2.0/api" fails
due to:
- Module "org.opentest4j" ships with a compiled module descriptor
- Its API documentation is generated and published without modules

Being in the transition phase from the non-modular to the modular world, this kind of work-around will show up more often. Library authors will inject "module-info.class" files into their library JAR files ... without producing modular API documentation at the same time, for a while.

Perhaps, javadoc may try to fall-back to the non-modular API input format, if it cosumes a "-link"ed module that lacks modular API documentation files.

Modular example project:
https://github.com/sormuras/sandbox/tree/master/javadoc-link-non-modular

Log with the error messages:
https://github.com/sormuras/sandbox/runs/471844267#step:5:28
Comments
Christoph Langer recently labelled this issue with: jdk11u-fix-yes Looking forward to remove some workaround code from the JUnit 5 project configuration, soon. https://github.com/junit-team/junit5/issues/2278
13-07-2020
Fix request (11u) -- will label after testing completed. I would like to downport this for parity with 11.0.9-oracle. It does not apply clean, and I had to adapt the changes to the tests: http://mail.openjdk.java.net/pipermail/jdk-updates-dev/2020-July/003446.html Test are both passing.
07-07-2020
[~cstein] Having more control over the warning may be good, but it may be difficult to do it within the -Xdoclint mechanism. One reason is that -Xdoclint can be invoked from both java and java doc, and when invoked from javac, it does not have enough information to do the necessary checks.
10-04-2020
Great. Would it be possible to introduce a new group for the `-Xdoclint` option here? Like "-Xdoclint:link" for link-related warnings.
10-04-2020
I agree, that's not very nice. The reason is that the check is done per package, not per library. I'll see if I can find a way to reduce the redundant warnings.
10-04-2020
Running the MRE project "javadoc-link-non-modular" described in the issue with javadoc of "JDK build 15-ea+18-776" yields: javadoc -d bin/api -Xdoclint:-missing --module foo --module-source-path src --module-path lib -link https://download.java.net/java/early_access/jdk15/docs/api -link https://junit.org/junit4/javadoc/4.13 -link https://ota4j-team.github.io/opentest4j/docs/1.2.0/api -link https://javadoc.io/doc/org.assertj/assertj-core/3.15.0 Constructing Javadoc information... javadoc: warning - The code being documented uses modules but the packages defined in https://ota4j-team.github.io/opentest4j/docs/1.2.0/api/ are in the unnamed module. javadoc: warning - The code being documented uses modules but the packages defined in https://javadoc.io/doc/org.assertj/assertj-core/3.15.0/ are in the unnamed module. ... Generating bin\api\index.html... Generating bin\api\help-doc.html... 25 warnings With only two distinct warnings. The second one is repeated 23 times. A single warning per `-link` option usage would suffice, I guess.
10-04-2020
URL: https://hg.openjdk.java.net/jdk/jdk/rev/3b557aef43c4 User: hannesw Date: 2020-04-08 20:05:10 +0000
08-04-2020