Fix Javadoc search on JDK 11:

[dmitry-timofeev]

Fixed Javadoc search feature on JDK 11, which is currently used in our
scripts updating snapshot Javadocs on guava.dev and building
Guava releases, by adding no-module-directories flag.

This option is not present in javadoc tool from JDK 8 and 13+,
hence we use profiles to conditionally pass this flag on 9-12 only.

Note that on JDK 17 javadoc generation does not work,
as it seems to have changed the warning on LVTI usage in sources
to an error.

Fixes #5457

TESTED=Locally with mvn javadoc:javadoc for guava module and its android flavour on JDK 11

[cpovirk]

Failure under JDK8, which we run CI under. As expected:

Error: Exit code: 1 - javadoc: error - invalid flag: --no-module-directories

Maybe just add...

-Dmaven.javadoc.skip=true

...to...

guava/.github/workflows/ci.yml

Line 43 in e64ad26

run: mvn -B -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn install -U -DskipTests=true -f $ROOT_POM

...given that "actual" Javadoc generation (for snapshots) is handled by...

guava/.github/workflows/ci.yml

Line 83 in e64ad26

name: 'Generate latest docs'

[cpovirk]

Hmm, but then pre-commit CI won't check Javadoc generation, so we wouldn't hear about breakages until after the commit.

Maybe it makes more sense for the flag to be conditional on the Java version -- either in the CI config or in Maven, as I think you'd suggested.

@cgdecker in case he happens to have thought about this.

[cpovirk]

...not sure offhand why Truth doesn't show this same problem....

[cpovirk]

Sorry, I'm now going back through some of your earlier messages.

Arguably an even better way to approach this would be to always build with some new version of javac but then test with each version we're targeting. My guess, though, is that that's harder.

[cpovirk]

...but I guess it's nice for Guava users to be able to build Guava with different JDKs.

[dmitry-timofeev]

Thanks for taking a look!

Oh, I was convinced we skip javadocs by default, but I see it makes sense to run them after the integration tests if we also publish them on each commit.

I agree that punishing 17+ -using users and requiring a 3y-old JDK is not good :)

What do you think would be the best thing to do:

1. Support correct Javadoc generation on all JDKs (8, 9–12, 13+): requires a JDK-version activated Maven profile, like in this POM):
   • (+) Don’t depend on migrating all our release scripts to 17 — can fix this issue right now
   • (+) Will produce correct Javadocs on all JDKs
   • (-) / (?) A bit of extra complexity in the configs, but not too much
   • If we eventually accept that JDK 17+ is required for development, and javadoc generation is not needed on earlier JDKs, it is a temporary measure.
2. Skip Javadoc generation on 8 and 12+ (conditionally set maven.javadoc.skip through a JDK-version activated Maven profile):
   • (+) Don’t depend on migrating all our release scripts to 17 — can fix this issue right now
   • (-) Same complexity as ^, but less benefits
3. (If you anticipate that 17 issues will get addressed soon) Wait till migrate to 17:
   • (+) No changes needed , no extra complexity in the configs
   • (?) Search won’t work on Javadocs generated with 11, but, arguably, it won’t matter

[cpovirk]

Thanks. (3) has some chance of turning into a bunch of work, which I predict that I personally will not follow up on. So, between (1) and (2), I think you make a good case that (1) is nicer.

[dmitry-timofeev]

Changed to (1) and updated the reasoning in the description.

However, on JDK 17 it doesn't work just yet: #5801 (comment)