TypedAPI: First version of documentation (#509)

* Add documentation

Author: Anaethelion

.doc/index.asciidoc

@@ -9,3 +9,5 @@ include::overview.asciidoc[]
 include::installation.asciidoc[]
 
 include::connecting.asciidoc[]
+
+include::typedapi/index.asciidoc[]

.doc/typedapi/conventions/endpoints.asciidoc

@@ -0,0 +1,46 @@
+[[endpoints]]
+==== Endpoints
+
+All the available endpoints are generated in separate packages and assembled in the client. The `core` namespace is duplicated at the root of the client for convenient access.
+
+Each endpoint follows a factory pattern which returns a pointer to a new instance each time. This leads to a builder pattern allowing to directly chain the options before running your query.
+
+[source,go]
+-----
+res, err := es.Search().Index("index_name").AllowPartialSearchResults(true).Do(context.Background())
+-----
+
+If parameters are needed for the specific endpoint you are using, those will be present as arguments in the same order as the API:
+
+[source,go]
+------------------------------------
+es.Create("index_name", "doc_id").Do(context.Background())
+------------------------------------
+
+Otherwise, you can find them within the builder:
+
+[source,go]
+------------------------------------
+es.Search().Index("index_name").Do(context.Background())
+------------------------------------
+
+Alternatively each endpoint can be instantiated directly from its package:
+
+[source,go]
+------------------------------------
+transport, err := elastictransport.New(elastictransport.Config{})
+res, err = search.New(transport).Do(context.Background())
+------------------------------------
+
+The `Do` method takes an optional `context`, runs the request through the transport and returns the results as well as an error.
+
+For body-empty endpoints such as `core.Exists`, an additional method `IsSuccess` is available. As the `Do` method, it takes an optional `context`, drains and closes the body if needed, and returns a boolean alongside an error
+
+[source,go]
+-----
+if exists, err := es.Core.Exists("index_name", "doc_id").IsSuccess(context.Background()); exists {
+    // The document exists!
+} else if err != nil {
+    // An error occurred.
+}
+-----

.doc/typedapi/conventions/index.asciidoc

@@ -0,0 +1,18 @@
+[[conventions]]
+=== Conventions
+
+This section details the conventions upon which the typed client is built.
+
+* <<structure>>
+* <<naming>>
+* <<endpoints>>
+* <<requests>>
+* <<responses>>
+* <<types>>
+
+include::structure.asciidoc[]
+include::naming.asciidoc[]
+include::endpoints.asciidoc[]
+include::requests.asciidoc[]
+include::responses.asciidoc[]
+include::types.asciidoc[]

.doc/typedapi/conventions/naming.asciidoc

@@ -0,0 +1,7 @@
+[[naming]]
+==== Naming
+
+Whenever appropriate, names may be suffixed with an underscore:
+
+* To avoid collision with protected keywords (`range, `if`, `type`, and so on).
+* To reflect the presence of a leading underscore in the API like `\_index` vs `Index_` or `\_source` vs `Source_`.

.doc/typedapi/conventions/requests.asciidoc

@@ -0,0 +1,21 @@
+[[requests]]
+==== Requests
+
+Requests are modeled around structures that follows as closely as possible the {es} API and uses the standard `json/encoding` for serialization.
+Corresponding request can be found withing the same package as its endpoint and comes with a Builder that allows you to deep dive into the API by following the types.
+
+The builder is particularly useful around pointer fields and is embeddable within a standard struct declaration, such that these two declarations give you the same result:
+
+[source,go]
+------------------------------------
+types.QueryContainer{
+    Term: map[types.Field]types.TermQuery{
+        "name": {Value: "Foo"},
+    },
+}
+types.QueryContainer{
+    Term: map[types.Field]types.TermQuery{
+        "name": types.NewTermQueryBuilder().Value(types.NewFieldValueBuilder().String("Foo")).Build(),
+    },
+}
+------------------------------------

.doc/typedapi/conventions/responses.asciidoc

@@ -0,0 +1,4 @@
+[[responses]]
+==== Responses
+
+While not part of the initial release responses will be added at a later date.

.doc/typedapi/conventions/structure.asciidoc

@@ -0,0 +1,11 @@
+[[structure]]
+==== Structure
+
+The Typed client lives in the `typedapi` package within the `go-elasticsearch` repository.
+
+The entire client is summed in an index at the root of the package for convenient access after instantiation.
+
+Each endpoint resides in its own package within `typedapi` and contains the client for this endpoint, the `Request` struct along with its builder, if applicable.
+
+The requests are based on a collection of structures generated from the https://github.com/elastic/elasticsearch-specification[elasticsearch-specification] repository and gathered in a `types` package within `typedapi`.
+Each type comes with a fluent builder for convenient creation and discoverability.

.doc/typedapi/conventions/types.asciidoc

@@ -0,0 +1,23 @@
+[[types]]
+==== Types
+
+Requests and responses are relying on a collection of structures generated from the https://github.com/elastic/elasticsearch-specification[elasticsearch-specification] in the `types` package.
+Each type comes with json tags and a builder.
+
+==== Enums
+
+The {es} API has several instances of enumerations, each has a package within `types/enums`.
+An enum is declared as a type and each member of the enum is an exported variable with its value.
+The enum types serializes to the relevant API value, for example the `refresh` options which can be found in the Search API:
+
+[source,go]
+------------------------------------
+refresh.True => "true"
+refresh.False => "false"
+refresh.Waitfor => "wait_for"
+------------------------------------
+
+==== Unions
+
+To capture the expressiveness of the API union fields are represented by a type alias to an interface.
+Each type alias comes with a builder that lists the possible types for the underlying value.

.doc/typedapi/examples/aggregations.asciidoc

@@ -0,0 +1,23 @@
+[[aggregations]]
+==== Aggregations
+
+Given documents with a `price` field, we run a sum aggregation on `index_name`:
+[source,go]
+-----
+totalPricesAgg, err := es.Search().
+	Index("index_name"). // <1>
+	Request(
+		search.NewRequestBuilder().
+			Size(0). // <2>
+			Aggregations(
+				map[string]*types.AggregationContainerBuilder{
+					"total_prices": types.NewAggregationContainerBuilder(). // <3>
+						Sum(types.NewSumAggregationBuilder().Field("price")), // <4>
+				}).
+			Build(),
+	).Do(context.Background())
+-----
+<1> Specifies the index name.
+<2> Sets the size to 0 to retrieve only the result of the aggregation.
+<3> Specifies the field name on which the sum aggregation runs.
+<4> The `SumAggregation` is part of the `AggregationContainer` map.

.doc/typedapi/examples/getdoc.asciidoc

@@ -0,0 +1,24 @@
+[[retrieving_document]]
+==== Retrieving a document
+
+Retrieving a document follows the API as part of the argument of the endpoint.
+In order you provide the `index`, the `id` and then run the query:
+[source,go]
+-----
+res, err := es.Get("index_name", "doc_id").Do(context.Background())
+-----
+
+==== Checking for a document existence
+
+If you do not wish to retrieve the content of the document and want only to check if it exists in your index, we provide the `IsSuccess` shortcut:
+[source,go]
+-----
+if exists, err := es.Exists("index_name", "doc_id").IsSuccess(nil); exists {
+    // The document exists !
+} else if err != nil {
+   // Handle error.
+}
+-----
+
+Result is `true` if everything succeeds, `false` if the document doesn't exist.
+If an error occurs during the request, you will be granted with a `false` and the relevant error.