Skip to content

Commit

Permalink
Fix linking to JDK 21 from the Guava Javadoc.
Browse files Browse the repository at this point in the history
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](#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
  • Loading branch information
cpovirk authored and Google Java Core Libraries committed Jan 3, 2025
1 parent c03d604 commit 993aa76
Show file tree
Hide file tree
Showing 4 changed files with 4 additions and 8 deletions.
2 changes: 1 addition & 1 deletion android/guava/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@
</offlineLink>
</offlineLinks>
<links>
<link>https://docs.oracle.com/javase/21/docs/api/</link>
<link>https://docs.oracle.com/en/java/javase/21/docs/api/</link>
<link>https://errorprone.info/api/latest/</link>
<link>https://jspecify.dev/docs/api/</link>
</links>
Expand Down
4 changes: 1 addition & 3 deletions android/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@
<jspecify.version>1.0.0</jspecify.version>
<errorprone.version>2.36.0</errorprone.version>
<j2objc.version>3.0.0</j2objc.version>
<!-- Empty for all JDKs but 9-12 -->
<maven-javadoc-plugin.additionalJOptions></maven-javadoc-plugin.additionalJOptions>
<project.build.outputTimestamp>2024-01-02T00:00:00Z</project.build.outputTimestamp>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!--
Expand Down Expand Up @@ -328,7 +326,7 @@
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.11.1</version>
<version>3.11.2</version>
<configuration>
<jdkToolchain>
<version>21</version>
Expand Down
2 changes: 1 addition & 1 deletion guava/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@
</offlineLink>
</offlineLinks>
<links>
<link>https://docs.oracle.com/javase/21/docs/api/</link>
<link>https://docs.oracle.com/en/java/javase/21/docs/api/</link>
<link>https://errorprone.info/api/latest/</link>
<link>https://jspecify.dev/docs/api/</link>
</links>
Expand Down
4 changes: 1 addition & 3 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,6 @@
<jspecify.version>1.0.0</jspecify.version>
<errorprone.version>2.36.0</errorprone.version>
<j2objc.version>3.0.0</j2objc.version>
<!-- Empty for all JDKs but 9-12 -->
<maven-javadoc-plugin.additionalJOptions></maven-javadoc-plugin.additionalJOptions>
<project.build.outputTimestamp>2024-01-02T00:00:00Z</project.build.outputTimestamp>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!--
Expand Down Expand Up @@ -323,7 +321,7 @@
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.11.1</version>
<version>3.11.2</version>
<configuration>
<jdkToolchain>
<version>21</version>
Expand Down

0 comments on commit 993aa76

Please sign in to comment.