Update documentation

Author: russcam

docs/aggregations/aggregation-meta-usage.asciidoc

@@ -0,0 +1,89 @@
+:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/2.4
+
+:xpack_current: https://www.elastic.co/guide/en/x-pack/2.4
+
+:github: https://github.com/elastic/elasticsearch-net
+
+:nuget: https://www.nuget.org/packages
+
+////
+IMPORTANT NOTE
+==============
+This file has been generated from https://github.com/elastic/elasticsearch-net/tree/2.x/src/Tests/Aggregations/AggregationMetaUsageTests.cs. 
+If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
+please modify the original csharp file found at the link and submit the PR with that change. Thanks!
+////
+
+[[aggregation-metadata]]
+=== Aggregation Metadata
+
+Metadata can be provided per aggregation, and will be returned in the aggregation response
+
+==== Fluent DSL example
+
+[source,csharp]
+----
+s => s
+.Size(0)
+.Aggregations(a => a
+    .Min("min_last_activity", m => m
+        .Field(p => p.LastActivity)
+        .Meta(d => d
+            .Add("meta_1", "value_1")
+            .Add("meta_2", 2)
+            .Add("meta_3", new { meta_3 = "value_3" })
+        )
+    )
+)
+----
+
+==== Object Initializer syntax example
+
+[source,csharp]
+----
+new SearchRequest<Project>()
+{
+    Size = 0,
+    Aggregations = new MinAggregation("min_last_activity", Infer.Field<Project>(p => p.LastActivity))
+    {
+        Meta = new Dictionary<string,object>
+        {
+            { "meta_1", "value_1" },
+            { "meta_2", 2 },
+            { "meta_3", new { meta_3 = "value_3" } }
+        }
+    }
+}
+----
+
+[source,javascript]
+.Example json output
+----
+{
+  "size": 0,
+  "aggs": {
+    "min_last_activity": {
+      "min": {
+        "field": "lastActivity"
+      },
+      "meta": {
+        "meta_1": "value_1",
+        "meta_2": 2,
+        "meta_3": {
+          "meta_3": "value_3"
+        }
+      }
+    }
+  }
+}
+----
+
+==== Handling Responses
+
+[source,csharp]
+----
+response.ShouldBeValid();
+var min = response.Aggs.Min("min_last_activity");
+min.Meta.Should().NotBeNull().And.ContainKeys("meta_1", "meta_2", "meta_3");
+----
+

docs/aggregations/writing-aggregations.asciidoc

@@ -149,7 +149,7 @@ Now that's much cleaner! Assigning an `*Aggregation` type directly to the `Aggre
 
 An advanced scenario may involve an existing collection of aggregation functions that should be set as aggregations
 on the request. Using LINQ's `.Aggregate()` method, each function can be applied to the aggregation descriptor
-`childAggs` below) in turn, returning the descriptor after each function application.
+(`childAggs` below) in turn, returning the descriptor after each function application.
 
 ==== Fluent DSL example
 

docs/client-concepts/certificates/working-with-certificates.asciidoc

@@ -23,7 +23,8 @@ that generated the certificate is trusted by the machine running the client code
 to the cluster over HTTPS with the client.
 
 If you are using your own CA which is not trusted however, .NET won't allow you to make HTTPS calls to that endpoint by default. With .NET,
-you can pre-empt this though a custom validation callback on the global static`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
+you can pre-empt this though a custom validation callback on the global static
+`ServicePointManager.ServerCertificateValidationCallback`. Most examples you will find doing this this will simply return `true` from the
 validation callback and merrily whistle off into the sunset. **This is not advisable** as it allows *any* HTTPS traffic through in the
 current `AppDomain` *without* any validation. Here's a concrete example:
 
@@ -41,8 +42,9 @@ validation will not be performed for HTTPS connections to *both* Elasticsearch *
 ==== Validation configuration
 
 It's possible to also set a callback per service endpoint with .NET, and both Elasticsearch.NET and NEST expose this through
-connection settings `ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
-your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class`CertificateValidations`.
+connection settings (`ConnectionConfiguration` with Elasticsearch.Net and `ConnectionSettings` with NEST). You can do
+your own validation in that handler or use one of the baked in handlers that we ship with out of the box, on the static class
+`CertificateValidations`.
 
 The two most basic ones are `AllowAll` and `DenyAll`, which accept or deny all SSL traffic to our nodes, respectively. Here's
 a couple of examples.
@@ -84,7 +86,8 @@ public class AllowAllCertificatesCluster : ClusterBase
 If your client application has access to the public CA certificate locally, Elasticsearch.NET and NEST ship with some handy helpers
 that can assert that a certificate the server presents is one that came from the local CA.
 
-Some certificates do not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
+Some certificates do not include the CA in the certificate chain, in order to cut down on SSL handshake size. In those case you can use
+`CertificateValidations.AuthorityIsRoot` and pass it your local copy of the CA public key to assert that
 the certificate the server presented was generated using it
 
 [source,csharp]
@@ -120,7 +123,7 @@ the local CA certificate is part of the chain that was used to generate the serv
 Shield also allows you to configure a PKI realm to enable user authentication
 through client certificates.
 
-To authenticate with client certificates, you need to present both a public certificate `.cer`) and a private key `.key`
+To authenticate with client certificates, you need to present both a public certificate (`.cer`) and a private key `.key`
 as one certificate. The easiest way to do this is to generate a `pfx` or `p12` file from the `.cer` and `.key`
 and attach these to requests using `new X509Certificate(pathToPfx)`.
 

docs/client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc

@@ -22,7 +22,8 @@ NEST can use to issue client calls on.
 
 [IMPORTANT]
 --
-Despite the name, a connection pool in NEST is **not** like connection pooling that you may be familiar with from https://msdn.microsoft.com/en-us/library/bb399543(v=vs.110).aspx[interacting with a database using ADO.Net]; for example,
+Despite the name, a connection pool in NEST is **not** like connection pooling that you may be familiar with from
+https://msdn.microsoft.com/en-us/library/bb399543(v=vs.110).aspx[interacting with a database using ADO.Net]; for example,
 a connection pool in NEST is **not** responsible for managing an underlying pool of TCP connections to Elasticsearch,
 this is https://blogs.msdn.microsoft.com/adarshk/2005/01/02/understanding-system-net-connection-management-and-servicepointmanager/[handled by the ServicePointManager in Desktop CLR]
 and can be controlled by <<servicepoint-behaviour,changing the ServicePoint behaviour>> on `HttpConnection`.

docs/client-concepts/connection-pooling/building-blocks/request-pipelines.asciidoc

@@ -103,7 +103,8 @@ sniffingPipeline.FirstPoolUsageNeedsSniffing.Should().BeFalse();
 
 ==== Wait for first sniff
 
-All threads wait for the sniff on startup to finish, waiting the request timeout period. A https://msdn.microsoft.com/en-us/library/system.threading.semaphoreslim(v=vs.110).aspx[`SemaphoreSlim`]
+All threads wait for the sniff on startup to finish, waiting the request timeout period. A
+https://msdn.microsoft.com/en-us/library/system.threading.semaphoreslim(v=vs.110).aspx[`SemaphoreSlim`]
 is used to block threads until the sniff finishes and waiting threads release the `SemaphoreSlim` appropriately.
 
 We can demonstrate this with the following example. First, let's configure

docs/client-concepts/connection-pooling/sticky/sticky-sniffing-connection-pool.asciidoc

@@ -58,7 +58,7 @@ We set up a cluster with 4 nodes all having a different rack id
 				our Sticky Sniffing Connection Pool gives the most weight to rack_2 and rack_11.
 				We initially only seed nodes `9200-9203` in racks 0 to 3. So we should be sticky on rack_2.
 				We setup node 9202 to fail after two client calls in which case we sniff and find nodes
-			 `9210-9213` in which case we should become sticky on rack_11.
+				`9210-9213` in which case we should become sticky on rack_11.
 
 [source,csharp]
 ----

docs/client-concepts/connection/configuration-options.asciidoc

@@ -24,7 +24,8 @@ how the clients interact with Elasticsearch.
 
 ==== Options on ConnectionConfiguration
 
-The following is a list of available connection configuration options on `ConnectionConfiguration`; since`ConnectionSettings` derives from `ConnectionConfiguration`, these options are available for both
+The following is a list of available connection configuration options on `ConnectionConfiguration`; since
+`ConnectionSettings` derives from `ConnectionConfiguration`, these options are available for both
 Elasticsearch.Net and NEST:
 
 `BasicAuthentication`::

docs/client-concepts/connection/modifying-default-connection.asciidoc

@@ -31,7 +31,8 @@ The Desktop CLR implementation using `WebRequest` is the most mature implementat
 in production since the beginning of NEST. For this reason, we aren't quite ready to it give up in favour of
 a `HttpClient` implementation across all CLR versions.
 
-In addition to production usage, there are also a couple of important toggles that are easy to set against a`ServicePoint` that are not possible to set as yet on `HttpClient`.
+In addition to production usage, there are also a couple of important toggles that are easy to set against a
+`ServicePoint` that are not possible to set as yet on `HttpClient`.
 
 Finally, another limitation is that `HttpClient` has no synchronous code paths, so supporting these means
 doing hacky async patches which definitely need time to bake.
@@ -139,7 +140,8 @@ var settings = new ConnectionSettings(connectionPool, connection);
 var client = new ElasticClient(settings);
 ----
 
-The Connection limit has been increased from the default 80 to much higher and https://en.wikipedia.org/wiki/Nagle's_algorithm[nagling] has been enabled, which is disabled by default in the client.
+The Connection limit has been increased from the default 80 to much higher and
+https://en.wikipedia.org/wiki/Nagle's_algorithm[nagling] has been enabled, which is disabled by default in the client.
 
 NOTE: The client reuses TCP connections through .NET's internal connection pooling,
 so changing the connection limit to something really high should only be done with careful

docs/client-concepts/high-level/analysis/writing-analyzers.asciidoc

@@ -72,7 +72,8 @@ var createIndexResponse = client.CreateIndex("my-index", c => c
 
 ==== Configuring a built-in analyzer
 
-Several built-in analyzers can be configured to alter their behaviour. For example, the`standard` analyzer can be configured to support a list of stop words with the stop word token filter
+Several built-in analyzers can be configured to alter their behaviour. For example, the
+`standard` analyzer can be configured to support a list of stop words with the stop word token filter
 it contains.
 
 Configuring a built-in analyzer requires creating an analyzer based on the built-in one
@@ -156,7 +157,9 @@ public class Question
 ----
 
 Based on our domain knowledge of programming languages, we would like to be able to search questions
-that contain `"C#"`, but using the `standard` analyzer, `"C#"` will be analyzed and produce the token`"c"`. This won't work for our use case as there will be no way to distinguish questions about`"C#"` from questions about another popular programming language, `"C"`.
+that contain `"C#"`, but using the `standard` analyzer, `"C#"` will be analyzed and produce the token
+`"c"`. This won't work for our use case as there will be no way to distinguish questions about
+`"C#"` from questions about another popular programming language, `"C"`.
 
 We can solve our issue with a custom analyzer
 

docs/client-concepts/high-level/covariant-hits/covariant-search-results.asciidoc

@@ -21,7 +21,8 @@ NEST directly supports returning covariant result sets.
 Meaning a result can be typed to an interface or base class
 but the actual instance type of the result can be that of the subclass directly
 
-Let's look at an example; Imagine we want to search over multiple types that all implement`ISearchResult`
+Let's look at an example; Imagine we want to search over multiple types that all implement
+`ISearchResult`
 
 [source,csharp]
 ----