Is JavaDoc on the way?

Elastic Stack Elasticsearch
1

Hi,

is this only me who thinks that Elasticsearch Java API Client is not well documented? All we get from javadoc is basic information about names of methods. The short less than 10 words sentences als explainations for classes or methods mostly just don't help in understanding.

Example: UpdateRequest (java-client 8.2.2 API)

I was not able to programm that because i was not able to find out what a TDocument nor a TPartialDocument is. Well later i found out that a TDocument is the Class.class of the Object i want to send. Thus i was able to use

client.update(upre -> upre.index("foo").id("bar").doc(r5), Rechnung.class);

But i was not able to use "UpdateRequest"-Class in a standalone-code-line.

The Javadoc just says

Updates a document with a script or partial document.

as a description for UpdateRequest. It does not explain TDocument or TPartialDocument. The super-class

doesn't have any sentence as explaination indeed. So there was not chance of finding out how to use it.

It took me actually 2 weeks to find out.

tells:

 if you want to pass partial document then you need to pass <Void, Product> and if document as upsert then you need to pass <Product,Void>

Okay now i understand and i could develop:

UpdateOperation.Builder<Rechnung, Void> up = new UpdateOperation.Builder<Rechnung, Void>();
up.index("foo");
up.id("bar");
up.withJson(new StringReader(myjson));
BulkOperation bo3 = new BulkOperation.Builder().update(up.build()).build();

But these explainations need to be in a javadoc in my moderate opinion. Example usage of the Class is important for a javadoc, too.

Thanks - Enomine

2

Definitely. I'd recommend that you propose what you wrote as a PR for this class so the rest of the community can benefit from this as well.

I'm sure @swallez will be happy to merge it.

3

What is a PR

Thanks - Enomine

4

A Pull Request.

5

Actually a Pull Request will not work in this case, as the code is generated. We have to add this documentation in the API specification used to generate the code.

1 Like
6

Okay.
Well actually this was only an example of which kind of information are missing in the current javadoc of much classes. The request is: Are you aware of this and is it planned to add a well done javadoc somewhere in future releases?

Thanks - Enomine

7

I want to let you know where the shoe pinches for people like me who try to get into Elasticsearch but miscarry at some points where the Elastic dokumentation can't help.

Thanks - Enomine

8

Good to know.

Maybe we could encourage the community to contribute to the specification then?

9

Question on that:

principles of commenting / javadoc:
a) less information is better than no information
b) no information is better than wrong information

So if the community would contribute then the information could be wrong and this is worse than no information. Shouldn't the author him/her self write javadoc? The author has the view over the whole framework and can make context / connection. I, as an example, only see that lone class and cannot write an explanation that explains it in an general purpose / meta information.

Thanks - Enomine

10

So if the community would contribute then the information could be wrong and this is worse than no information.

That's why we have reviews. No worries.

11

:+1:

12

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.