[docs] Update with the latest changes and use compilable examples #52
Conversation
swallez
added
Area: Documentation
Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
|
@szabosteve as discussed, I've added the test code in a separate commit in both the |
docs/api-conventions.asciidoc
Outdated
| and ease distinguishing what identifiers belong to the API or to the framework. | ||
| Client is built, such as `Query._kind()`. These methods and properties are | ||
| prefixed with an underscore to both avoid any naming conflicts with API names, | ||
| and allow to easily distinguish what belongs to the API from what belongs to the |
There was a problem hiding this comment.
"and as an easy way to distinguish the API from the framework"
docs/api-conventions.asciidoc
Outdated
| It becomes particularly useful with complex nested queries like the one below, | ||
| taken from the | ||
| Note in the above example that builder variables are only used to start a chain | ||
| of property setters. Their name therefore doesn't matter much and can be shortened |
There was a problem hiding this comment.
"The names of these variables are therefore unimportant and can be shortened"
| Java syntax, we name them with an underscore followed by the depth of the item, | ||
| i.e. `_0`, `_1`, and so on. This removes the need for finding names and makes | ||
| the code easier to read by reducing the number of identifiers. Correct indentation | ||
| also allows the structure of the query to stand out. |
There was a problem hiding this comment.
"This example also highlights a useful and recommended naming convention for builder parameters in deeply nested structures. For lambda arguments, Kotlin provides it and Scala allows use of _; this can be approximated in Java by using an underscore prefix followed by a number representing the depth level (i.e. _0, _1, and so on). Not only does this remove the need to generate throw-away variable names, but it also improves code readability."
docs/api-conventions.asciidoc
Outdated
|
|
||
| Properties of type `List` and `Map` are exposed by object builders as a set of overloaded | ||
| methods that _update_ the property value, by appending to lists and adding new entries to maps | ||
| (or replacing existing ones). |
There was a problem hiding this comment.
It it worth clarifying that these are "additive-only" and should not be considered regular collection objects, due to a lack of "remove" methods, and similar?
|
@technige I added a commit with your suggestions and also added a paragraph explaning that lists and maps are never |
Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
… (#53) Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
Update/cleanup documentation and refactor code examples as included sections of test code, so that code snippets in the docs are compiled and tested.