Extract content from a file about docs HOT 4 CLOSED

+1 from my side to keep documentation examples under build and test cycles.

Not sure if we should first take a step back maybe and review what we want to accomplish.

Here's my gist after updating the docs for the Java API query dsl examples:

What we have at the moment is the following:

https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/bool.html

IMHO on the one hand this is not enough as for most queries it doesn't cover all options, so no real reference documentation there. It duplicates documentation as well as what is written there to some part is written in JavaDoc already. On top it's never built so easily forgotten when ppl change the API.

Another approach I've seen in the wild:

https://github.com/randomizedtesting/randomizedtesting/tree/master/examples/maven/src/main/java/com/carrotsearch/examples/randomizedrunner

To me those are complimentary to the reference style docs JavaDoc typically provides: It's giving real world examples centred around some topics. On top it has the advantage of being under build and test cycles.

Lastly there's the Lucene JavaDoc only approach:

https://lucene.apache.org/core/4_1_0/core/index.html?overview-summary.html

Close to the code, examples still not under build and test cycles.

Me personally if I was a user I would love to see the second type of docs - could be as real code examples in some test package. If it's done using the style @dadoonet outlined above it would be better in line with the rest of our documentation - great as well. For such documentation I personally find it frustrating if there are errors in the docs, so to me it would be really important to keep them under build and test cycles.

In addition I would wish for detailed reference docs in our JavaDocs, potentially linked from the examples above.

from docs.

It basically means that when a developer changes whatever part of code, the documentation is automatically updated with the new content.

+1 and will help our doc from becoming stale over time :)

from docs.

Hmmm. Just found this doc today: http://mrhaki.blogspot.fr/2014/04/awesome-asciidoc-include-partial-parts.html

May be this is something we can use easily? I'm going to give it a try.

from docs.

Closed by elastic/elasticsearch#24354. Thanks to @nik9000 !

from docs.