Giters

google / guava

Google core libraries for Java

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Inheriting Javadoc from the JDK _and_ linking to the JDK broke at some point

cpovirk opened this issue · comments

commented

e.g., https://guava.dev/BiMap has blank descriptions for put, putAll, and values, and it has no links for types like java.lang.Object and java.util.Map

commented

I can reproduce this locally with ./mvnw clean javadoc:javadoc with JAVA_HOME pointed to Java 11. I can also reproduce it with mvn, so it's not likely to be related to my recent Maven Wrapper change.

commented

The info disappeared at bdbcb37, so it's been almost a year :\

A change from around that time that looks plausibly related is 8a676ad. I could believe that the cause is java.specification.version.

commented

Yes, I can fix it by removing the java.specification.version change. But that point, Javadoc prints a bunch of warnings under JDK 11, and it fails entirely (or at least pretty badly) under JDK 17.

I could believe that the problem is somehow related to modules. Roughly, the JDK sources might be "hidden" by the JDK modules?

I briefly tried messing with the path we pass to Javadoc, passing ${project.build.directory}/jdk-sources/java.base instead of just ${project.build.directory}/jdk-sources, but that didn't help.

I tried removing our exclusion of the JDK's module-info files, but then I got:

[ERROR] Creating an aggregated report for both named and unnamed modules is not possible.
[ERROR] Ensure that every module has a module descriptor or is a jar with a MANIFEST.MF containing an Automatic-Module-Name.
[ERROR] Fix the following projects:
[ERROR]  - com.google.guava:guava

So it's possible that things would go better if Guava were a real module (#2970). (Presumably Javadoc would be willing to inherit Javadoc across module boundaries.)

I could probably "fix" this by setting the Javadoc source version back to 8 for JDK 11 (where we know that it works). But we know that it doesn't work for JDK 17, so this would be only a temporary fix.

commented

(Presumably Javadoc would be willing to inherit Javadoc across module boundaries.)

I guess I'm somewhat pessimistic about that, given that the sources probably are being hidden entirely.

But I could believe that we could do something with --patch-module or something. And in fact, after poking around a little, I found https://bugs.openjdk.org/browse/JDK-8300694. (That bug even notes that this worked for Guava at the latest release but not at head at the time :))

I'm not excited about trying to get this to work, but if anyone wants to try to wire it up, either the temporary solution of using <source>8</source> under JDK11 or the permanent(?) solution of figuring out --module-path, please be my guest.

commented

Oh, and in all this, I've been forgetting about the problem linking to the JDK. I would guess (but haven't checked) that that problem is a result of the same commit as the other problem. It may be related to how we still link (well, try to link) to JDK 9, which of course supports the module system but does not yet include the module name in the path of the Javadoc it produces.