Add Badge to javadoc.io on README

[vorburger]

@cpovirk wanna merge this?

[cpovirk]

We have some Javadoc links under https://github.com/google/guava#snapshots-and-documentation. There are a few ways that we could change those to be more in line with what you have in this PR:

1. We could move them up closer to the top.
2. We could make them badges.
3. We could link to the latest release instead of to the snapshot docs.
4. We could link to javadoc.io instead of our hosted docs.
5. We could provide easier access to the Android flavor's docs in addition to the JRE flavor's.

We should probably do at least some of those. I'm interested in which ones you would see as most valuable.

[cpovirk]

(We should also think about how much to keep the GitHub landing page in sync with https://guava.dev/, which likewise has links to Javadoc.)

[vorburger]

Thank You for the prompt feedback and for considering this!

I'm interested in which ones you would see as most valuable.

My feedback would be to do the following:

4. We could link to javadoc.io instead of our hosted docs.

Unless there are any objections to pointing to linking to javadoc.io (I certainly respect if there are! But are there?), merge this PR as-is; one of the things which I like about it and that "brings value" (IMHO) is that they let folks easily switch between and read the docs for all versions published to Maven Central.

But I would NOT do that "instead of our hosted docs" - because those reflect "what's on master right now" - which is great, and worthwhile keeping! (And javadoc.io apparently does not show -SNAPSHOT looks like they base it off actually published releases, only.)

2. We could make them badges.

I think that would "look nice". I've also noticed a number of (Java) libraries doing this, so it seems like an at least somewhat popular "custom". Would you like me to have a look into how this may be able to be done, and propose a follow-up to this PR? Or prefer seeing this added here?

BTW: I have to admit something, rather silly: You know why at least me, and perhaps others, haven't noticed the existing Javadoc links? I just Ctrl-F "javadoc", and... nothing! 🤣 I have now also raised #7601 specifically just for taking care of that.

1. We could move them up closer to the top.

With #7601 and badges (if we do), then IMHO no need (for me).

3. We could link to the latest release instead of to the snapshot docs.
4. We could provide easier access to the Android flavor's docs in addition to the JRE flavor's.

I would consider these points as one single and the same... TBH I only just figured via "URL hacking" that e.g. https://javadoc.io/doc/com.google.guava/guava/33.2.0-android/index.html and https://javadoc.io/doc/com.google.guava/guava/33.2.0-jre/index.html are available.

The real question here is if it would be easy for project maintainers to keep updating the README after every release to add a link to the latest one. Personally... these things often have a way of getting out of date, don't they? Given that javadoc.io does it based on Maven Central releases, why bother? Just my 2 cents.

(We should also think about how much to keep the GitHub landing page in sync with https://guava.dev/, which likewise has links to Javadoc.)

Is that page generated using (something like) Jekyll from the README.md, or is it separately maintained? I'm confused because it LOOKS identical, but it doesn't have e.g. the same title, and the Badges.

[cpovirk]

Dumping random thoughts before I'm OOO for a couple hours:

• guava.dev uses separate source: https://github.com/google/guava/blob/gh-pages/index.md. We manually update it to match when necessary, but that's not necessary too often because...
• Both guava.dev and the GitHub landing page are updated automatically during our release process. And while it would be nice for the automation to not have to update them, we like having the version number available in our examples of how to add Guava as a dependency, so we'd want it even without using it for Javadoc. (Of course, it would be nice to have a generic "How to add this library as a dependency" page that we're fully happy to link to.)
• It's sad that links to Guava Javadoc may point to our site or to javadoc.io, to JRE or Android, to a snapshot or to any of a number of given versions :( It's hard to say whether using javadoc.io more would overall help or hurt that on various time horizons.
  • In the distant past, I had trouble linking to javadoc.io from other Javadoc. Presumably relatedly, we link to non-javadoc.io sources for Guava's own links to other projects. I wonder what most projects do.

[cpovirk]

• It's possible that the first person to visit javadoc.io for a new Guava release has to wait for it to generate? Or does it use the actual Javadoc published to Maven Central? I forget how it works.... If we wanted to, we could always include a step in the release process to automatically/manually visit the page to trigger any necessary work.

[cpovirk]

OK, it says "new versions auto-detected within 24 hours." That suggests that we wouldn't need to actively do anything. Now, waiting 24 hours is worse than not waiting 24 hours, but I'm sure it makes no difference in most cases.

[cpovirk]

• I guess we could also wonder what the chances are that javadoc.io would stop working someday. We could of course just change our own links at that point, but that may leave behind broken links elsewhere on the web.
• Our Javadoc URL structure might end up changing when we make Guava a proper module (though I'm not sure that a change to the URL structure is strictly required), similar to Generate module-style Javadoc jspecify/jspecify#712. We might have more freedom to add appropriate redirects if we're fully in control of the hosting of the Javadoc. But it seems as if it at least ought to be possible for our build to generate HTML files with any redirects that we want, and presumably javadoc.io would pick those up (either from building our Javadoc itself or from downloading from Maven Central).

[cpovirk]

• Self-hosting does also let us fix things faster, including in my recent experiments with updating our Javadoc version and fixing links. Now, I don't do that often. And the fixes rarely matter. And as you say, our snapshot docs don't have to be the only docs. But that's another reason that our self-hosted copy is arguably nicer, so it's nice not to nudge people toward the javadoc.io option if it's slightly worse in those ways.
• Now, if we were able to eliminate the self-hosted Javadoc entirely, that would save us from hitting a hiccup that sometimes arises in our release process (in which we try to push the new Javadoc, only to conflict with some other concurrent push). But that should be easy to fix (with an automated rebase) if we care enough :)

[vorburger]

Makes sense. With "JavaDoc" now mentioned (for Ctrl-F), and badges just coming up), I'm very happy to simply close this (unmerged). OK for you?