Skip to content

Commit

Permalink
Fix Javadoc search.
Browse files Browse the repository at this point in the history
I'm using the fix from https://stackoverflow.com/a/52603413/28465

Note that this fix can break links to the JDK Javadoc in some cases (https://stackoverflow.com/a/56394202/28465), and apparently there are alternative solutions that can avoid that (https://stackoverflow.com/a/56641766/28465).

However, because we are linking to JDK version *1.7*, we don't need or want module names in those URLs, so this solution works fine for us.

Before this CL, our linking to JDK 1.7 happens implicitly based on the -source value for the *compiler* plugin. I've decided that this is as good a time as any to make an explicit choice instead. So my change to link to JDK 1.7 is a no-op.

I considerd updating our configuration to point to JDK 1.8 or 1.9, but those use a different format for anchors than the JDK 11 javadoc generates (clone-- vs. clone()), so links to specific methods wouldn't go to those methods anymore.

I also tried pointing to JDK 10, which does use the same anchor format as JDK 11 javadoc, but then I run into problems related to modules, and I don't want to get into that.

And once you get to JDK 11+, then you need your JDK links to include the module in the URL, so I'd need to explore the alternative fix. *Plus*, I assume I'd have the same other modules problems as I saw with JDK 10.

(Note that the --no-module-directories option that I've added doesn't work with JDK 1.8. Neither does the existing --frames option. Ideally, I might put these in a <profile>. But given the number of settings that need to be aligned just right, any of which could potentially interact with the version of javadoc that we're using, it's probably better if we just require a newer version. Ideally I'd set up Maven to require JDK 11 (to ensure that javadoc generates anchors in the format we expect), but I haven't bothered yet.)

Fixes #670

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=303114889
  • Loading branch information
cpovirk authored and nick-someone committed Mar 26, 2020
1 parent 825ca13 commit 1af73cb
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,9 @@
<additionalOption>--frames</additionalOption>
<additionalOption>-Xdoclint:-html</additionalOption>
</additionalOptions>
<additionalJOptions>
<additionalJOption>--no-module-directories</additionalJOption>
</additionalJOptions>
<doctitle>Truth ${project.version}</doctitle>
<windowtitle>Truth ${project.version}</windowtitle>
<quiet>true</quiet>
Expand All @@ -269,11 +272,13 @@
<docencoding>UTF-8</docencoding>
<charset>UTF-8</charset>
<overview>overview.html</overview>
<detectJavaApiLink>false</detectJavaApiLink>
<links>
<!-- TODO(cpovirk): Link to the version that we depend on? -->
<link>https://google.github.io/guava/releases/snapshot-jre/api/docs</link>
<link>https://developers.google.com/protocol-buffers/docs/reference/java</link>
<link>https://junit.org/junit4/javadoc/latest/</link>
<link>https://docs.oracle.com/javase/7/docs/api/</link>
</links>
<source>8</source>
<sourceFileExcludes>
Expand Down

0 comments on commit 1af73cb

Please sign in to comment.