Fix linking to JDK 21 from the Guava Javadoc. #1379
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![copybara-service[bot]](https://avatars.githubusercontent.com/in/44061?s=60&v=4){kind=small}
Currently, we link to JDK 8 instead. It's a long story: I had moved us to 21 in cl/696975523, but that got undone by cl/711476575: The latter change reinstated a flag (`--no-module-directories`) from cl/413922237 that had been accidentally circumvented by cl/655647768. (cl/655647768 changed the VM that we use to run _Maven itself_, and our Javadoc configuration was wrongly triggered by the version of _that_ VM, rather than the version used to run Javadoc.) That flag, which worked around a bug whose fixed has conveniently [been backported](https://bugs.openjdk.org/browse/JDK-8215291?focusedId=14506100&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-14506100), somehow also caused [a warning/error](google/guava#6790 (comment)): ``` [WARNING] warning: URL https://docs.oracle.com/javase/21/docs/api/element-list was redirected to https://docs.oracle.com/en/java/javase/21/docs/api/index.html -- Update the command-line options to suppress this warning. ``` In the cases in which it's only a warning (as when using Javadoc 21, as opposed to Javadoc 23), it is also a sign that linking to JDK 21 failed. Javadoc apparently then falls back to linking to JDK 8. (I'd say that the linking to Java 8 (rather than just failing to link altogether) is a result of [JDK-8216497](https://bugs.openjdk.org/browse/JDK-8216497) except that that change seems to have been new in Javadoc 16.) The fix is to change the link to include the `/en/java/` segments. This is a change relative to where Java _8_ Javadoc lives to this day. (Since Java 8 Javadoc is still at the old path, I did _not_ touch a similar link in _Caliper_, which links to Java 8.) (I suspect that we could now upgrade to Javadoc 23 if we wanted. I think we could already _link_ to a newer JDK version if we wanted. I don't think I thought very hard about picking 21 for that.) We do still see another warning, but _shrug_: ``` [WARNING] warning: The code being documented uses packages in the unnamed module, but the packages defined in https://docs.oracle.com/en/java/javase/21/docs/api/ are in named modules. ``` Also: Bump `maven-javadoc-plugin`, and remove a now-unused Maven property. Also, in Truth: Prevent Truth's JDK linking from breaking similarly when we upgrade the version of Javadoc that we use to generate its docs. And remove its attempted `--no-module-directories` configuration, too: That flag is no longer necessary with recent Javadoc 11 versions, and it turns out that it hasn't actually been used since cl/509829752.... RELNOTES=n/a PiperOrigin-RevId: 711811272
copybara-service
bot
force-pushed
the
test_711793008
branch
from
37ea373 to
3919c28
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fix linking to JDK 21 from the Guava Javadoc.
Currently, we link to JDK 8 instead. It's a long story:
I had moved us to 21 in cl/696975523, but that got undone by cl/711476575: The latter change reinstated a flag (
--no-module-directories) from cl/413922237 that had been accidentally circumvented by cl/655647768. (cl/655647768 changed the VM that we use to run Maven itself, and our Javadoc configuration was wrongly triggered by the version of that VM, rather than the version used to run Javadoc.) That flag, which worked around a bug whose fixed has conveniently been backported, somehow also caused a warning/error:In the cases in which it's only a warning (as when using Javadoc 21, as opposed to Javadoc 23), it is also a sign that linking to JDK 21 failed. Javadoc apparently then falls back to linking to JDK 8. (I'd say that the linking to Java 8 (rather than just failing to link altogether) is a result of JDK-8216497 except that that change seems to have been new in Javadoc 16.)
The fix is to change the link to include the
/en/java/segments. This is a change relative to where Java 8 Javadoc lives to this day. (Since Java 8 Javadoc is still at the old path, I did not touch a similar link in Caliper, which links to Java 8.)(I suspect that we could now upgrade to Javadoc 23 if we wanted. I think we could already link to a newer JDK version if we wanted. I don't think I thought very hard about picking 21 for that.)
We do still see another warning, but shrug:
Also: Bump
maven-javadoc-plugin, and remove a now-unused Maven property.Also, in Truth: Prevent Truth's JDK linking from breaking similarly when we upgrade the version of Javadoc that we use to generate its docs. And remove its attempted
--no-module-directoriesconfiguration, too: That flag is no longer necessary with recent Javadoc 11 versions, and it turns out that it hasn't actually been used since cl/509829752....RELNOTES=n/a