README -> Documentation does not point to Javadoc

[goldbach00009]

The link in README does not point to any Javadoc, but to the generic guidance for Stripe web API. A google search for Javadoc associated with a specific version brings up websites not related to stripe.

It could be that my expectation is wrong and there is no Javadoc associated to this API, to describe the various objects and their responsibilities. If that is the case, it should be briefly mentioned, perhaps.

README.md

Documentation

Please see the Java API docs for the most up-to-date documentation.

[remi-stripe]

@goldbach00009 Today the library contains the javadoc library so that the documentation appears in your IDE but we don't generate or host a separate javadoc just yet. I do see how that could be useful though so tagging as future! cc @mickjermsurawong-stripe

[mickjermsurawong-stripe]

Hi @goldbach00009,
Ah "Java API docs" could easily be understood as the standard java docs. As remi, pointed out, we don't host java docs yet. For now, do you think under the documentation rephrasing as:
"Stripe API reference for Java" would have made it clearer to you?

[goldbach00009]

Yes, it is clearer and perhaps, for the time being, the simple additional information that the standard Javadoc is available in the JAR could be useful, given that the https://stripe.com/docs/api/java is cross-language and, afaik, there is no Javadoc in there as well. I did not think of looking in the JAR, my first idea was to google for it instead...!

[ob-stripe]

We could easily host the Javadoc HTML on GitHub Pages or similar, but I'm not convinced it'd be terribly useful -- most of the Javadoc is automatically generated from the OpenAPI spec and the information is going to be the same as / a subset of the API reference. The Javadoc is definitely helpful for IDEs, but if you're looking for an external reference, then you're probably better off looking at the "real" API reference on Stripe's site than the HTML version of Javadoc.

On the other hand, it wouldn't cost us much to host the Javadoc HTML somewhere, and maybe Java devs can navigate the Javadoc HTML more efficiently than the Stripe's API reference.

[ob-stripe]

Just wanted to let you know that we're now hosting the library's Javadoc at https://stripe.dev/stripe-java. The README has been updated to mention it.

Closing, but feel free to reply to let us know what you think!