Improve Java API documentation with more detail and best practice examples

[geekpete]

Elasticsearch version: 5.x

There are a few different tickets that have been created for what I see as a single bug in lack of minimum detail/examples in our documentation for the Java API.

This ticket is to provide a place to collate this effort since creating the minimum level of documentation probably shouldn't be done in a piecemeal or adhoc way as people encounter individual issues with it.

Related tickets in the Elastic repo:

• Documentation for reindex API is not available for JAVA API  #24203 - Documentation for reindex API is not available for JAVA API
• Documentation for UpdateByQuery #18787 - Documentation for UpdateByQuery
• Link to javadocs #23761 - Link to javadocs
• JBoss Module doc needs updating #18848 - JBoss Module doc needs updating
• Request to change name of WrapperQueryBuilder (org.elasticsearch.index.query) #11591 - Request to change name of WrapperQueryBuilder (org.elasticsearch.index.query)

There's also the valuable discussion in our Elastic Cloud X-Pack Transport Example repo that has a specific example of using HostFailureListener to deal with dns/ip changes for Elasticsearch endpoints that needs to be well documented with a code example as best practice in docs for Java API client usage:

• Transport client best practices found-shield-example#9 - Transport client best practices

So we need to determine some minimum level of documentation requirement then fulfil such a requirement by improving the documentation.

The documentation could then be turned into a solid example in the Elastic Cloud X-Pack Transport Example repo as a reference.

[nik9000]

Given that we're really working to replace the transport client with the high level rest client, maybe we're better off concentrating on making sure the documentation for that is sound rather than expanding on the transport client's docs.

[geekpete]

People will still be using the transport client for some amount of time even after the replacement client is GA that might warrant adding at least some improvement to the transport client docs though?
But I do agree that we should definitely make the new REST client as great as we can as far as detail and examples.

And yes, a matter of priorities, but how about we at least create a skeleton list of what's missing/needed and then community effort/PRs could be directed to fill those docs gaps where possible as low hanging fruit type tasks?

[dadoonet]

Here is the thing.

I initially proposed to add a Java API docs QA module in our Gradle build so I would have been able to backport the project I have locally on my laptop which helped me to build the Java documentation until now. But this has been qualified as not useful because we have already a lot of Java tests around. So I'm still doing updates from time to time but manually.
My goal was to automatically import into the documentation the lines of code so we are never de-synchronized anymore. (elastic/docs#4). Thanks to @nik9000 with #24354, we now have that import mechanism.

I was adding to my backlog some of the missing APIs when people were asking for that in discuss. For example: #22235.

But then we started to build the REST Client and it was clear to me that because we are going to deprecate it anytime soon and remove it at some point, continuing to build that deprecated doc was a waste of time. That's the reason I started to contribute instead on the High Level Client doc as you can see in #23351.

So what I'd do if and only if we want to update the transport documentation:

• Add a QA Java Transport Client documentation module (with all my existing code in it) or add integration tests for the transport module
• Move the current Java doc to use what Nik Built
• Add a QA REST HL Client Java documentation module (or extract from the tests of the HLClient module - which might be better). Would be awesome to be able to reuse the transport client part to make sure we can still migrate easily from one client to the other.

My 2 cents.

[javanna]

I am leaning towards closing this issue. We've been taking all this into account while writing the high level REST client docs. We are adding extensive examples for each API, and we test all the snippets to make sure that they don't get outdated over time. I am working on adding links to the javadocs as well.

As for transport client, we have some issues open which are listed in the description of this issue, but I don't see us doing big rewrites of its docs at this point. We are rather focussing on having good docs for the new client. Any objections on closing this issue?

[dadoonet]

Any objections on closing this issue?

No objection from my side.

[javanna]

No objections, closing. Please have a look at the docs for the high level REST client and open specific issues/PRs whenever you see something that can be added or improved.

[geekpete]

Thanks for looking at this team. We'll add to the docs as we come across more examples to improve where we can over time, but I agree that the new client focus is the right way forward with the available resources.