We found this problem when we migrated Apache Lucene to minimum Java 11. Apache Lucene uses a documentation linter to check for broken links and so we recognized that bug very fast. Although it's a bad idea with modules to have split packages (org.apach.lucene.something in different jar files), we can't easily fix this (we are not yet using modules!). In short: Lucene JAR files have same package in different JARs.

We also add crosslinks in Javadocs, e.g., the analysis JAR has org.apache.lucene.analysis.standard, but also Lucene Core has it). In a third jar file we have links to a class in this package which resides in Lucene Core. Lucene adds "-link" to Javadoc command line when calling for each dependent Lucene module, staring with the "Lucene Core" one first.

In all old JDK versions up to Java 11.0.1, the order of "link" elements when calling Javadocs are evaluated left to right and only the first occurence of a java package is taken. Lucene passes the link element in the order "important" to "less important". Javadocs tool was taking the package from the first link that matches (so earlier package name wins).

Before JDK-8205593 the lookup map was populated by reading all the packages-files, checking if package is already in package lookup map and add it only if its not there. By that "first-wins" (it's only inserted when seen for first time). After the Javadocs JDK-8205593 patch, the containKey() was removed and all packages are added to map, so "last-wins".

Before: http://hg.openjdk.java.net/jdk/jdk/rev/f7d40158eb2f#l7.60 (see !containsKey)
After: http://hg.openjdk.java.net/jdk/jdk/rev/f7d40158eb2f#l7.196 (see the put at end, so if same package in same Jigsaw module "unnamed", its overwritten and so latest item wins)

So that means all of Lucene's Javadocs are broken after Java 11.0.2, which is horrible as it happens depending on which minor version of JDK you are using. 11 and 11.0.1 works, 11.0.2. is broken. So depending on the JDK version we produce incorrect links.

As it is unlikely to be fixed in Java 11, we added a workaround: We have a regex ANT task patching the element-list files after building the Javadocs and removing all lines in all Lucene JAR files that have duplicates from the Lucene Core JAR file.

But this should be fixed by adding the "containskey" back (see above, also works with the map of maps).