Update documentation

Author: russcam

docs/aggregations/writing-aggregations.asciidoc

@@ -202,7 +202,7 @@ s => s
 
 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.
 
 [source,csharp]
 ----
@@ -228,6 +228,7 @@ return s => s
         );
 ----
 <1> a list of aggregation functions to apply
+
 <2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
 
 [[handling-aggregate-response]]
@@ -271,5 +272,6 @@ var maxPerChild = childAggregation.Max("max_per_child");
 maxPerChild.Should().NotBeNull(); <2>
 ----
 <1> Do something with the average per child. Here we just assert it's not null
+
 <2> Do something with the max per child. Here we just assert it's not null
 

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

@@ -40,7 +40,7 @@ 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
+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`.
 
@@ -57,7 +57,7 @@ public class DenyAllCertificatesCluster : SslAndKpiXPackCluster
 {
     protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
         .ServerCertificateValidationCallback((o, certificate, chain, errors) => false)
-        .ServerCertificateValidationCallback(CertificateValidations.DenyAll); <1>
+        .ServerCertificateValidationCallback(CertificateValidations.DenyAll); <1>
 }
 ----
 <1> synonymous with the previous lambda expression
@@ -72,7 +72,7 @@ public class AllowAllCertificatesCluster : SslAndKpiXPackCluster
 {
     protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
         .ServerCertificateValidationCallback((o, certificate, chain, errors) => true)
-        .ServerCertificateValidationCallback(CertificateValidations.AllowAll); <1>
+        .ServerCertificateValidationCallback(CertificateValidations.AllowAll); <1>
 }
 ----
 <1> synonymous with the previous lambda expression
@@ -82,7 +82,7 @@ public class AllowAllCertificatesCluster : SslAndKpiXPackCluster
 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.
 
-If you use X-Pack's {ref_current}/certutil.html[+certutil+ tool] to generate SSL certificates, the generated node certificate
+If you use X-Pack's {ref_current}/certutil.html[`certutil` tool] to generate SSL certificates, the generated node certificate
 does 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
@@ -118,11 +118,11 @@ the local CA certificate is part of the chain that was used to generate the serv
 ==== Client Certificates
 
 X-Pack also allows you to configure a {xpack_current}/pki-realm.html[PKI realm] to enable user authentication
-through client certificates. The {ref_current}/certutil.html[+certutil+ tool] included with X-Pack allows you to
+through client certificates. The {ref_current}/certutil.html[`certutil` tool] included with X-Pack allows you to
 generate client certificates as well and assign the distinguished name (DN) of the
 certificate to a user with a certain role.
 
-By default, the `certutil` tool only generates a public certificate `.cer`) and a private key `.key`. To authenticate with client certificates, you need to present both
+By default, the `certutil` tool only generates a public certificate (`.cer`) and a private key `.key`. To authenticate with client certificates, you need to present both
 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)`.
 
@@ -136,12 +136,12 @@ You can set Client Certificates to use on all connections on `ConnectionSettings
 ----
 public class PkiCluster : CertgenCaCluster
 {
-    protected override ConnectionSettings Authenticate(ConnectionSettings s) => s <1>
+    protected override ConnectionSettings Authenticate(ConnectionSettings s) => s <1>
         .ClientCertificate(
             ClientCertificate.LoadWithPrivateKey(
-                this.Node.FileSystem.ClientCertificate, <2>
-                this.Node.FileSystem.ClientPrivateKey, <3>
-                "") <4>
+                this.Node.FileSystem.ClientCertificate, <2>
+                this.Node.FileSystem.ClientPrivateKey, <3>
+                "") <4>
         );
 
     //hide
@@ -153,8 +153,11 @@ public class PkiCluster : CertgenCaCluster
 }
 ----
 <1> Set the client certificate on `ConnectionSettings`
+
 <2> The path to the `.cer` file
+
 <3> The path to the `.key` file
+
 <4> The password for the private key
 
 Or per request on `RequestConfiguration` which will take precedence over the ones defined on `ConnectionConfiguration`

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

@@ -20,7 +20,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

@@ -101,7 +101,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/exceptions/unexpected-exceptions.asciidoc

@@ -58,8 +58,11 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> set up a cluster with 10 nodes
+
 <2> where node 2 on port 9201 always throws an exception
+
 <3> The first call to 9200 returns a healthy response
+
 <4> ...but the second call, to 9201, returns a bad response
 
 Sometimes, an unexpected exception happens further down in the pipeline. In this scenario, we
@@ -98,7 +101,9 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> calls on 9200 set up to throw a `WebException`
+
 <2> calls on 9201 set up to throw an `Exception`
+
 <3> Assert that the audit trail for the client call includes the bad response from 9200 and 9201
 
 An unexpected hard exception on ping and sniff is something we *do* try to recover from and failover to retrying on the next node.
@@ -143,6 +148,8 @@ audit = await audit.TraceUnexpectedException(
 );
 ----
 <1> `InnerException` is the exception that brought the request down
+
 <2> The hard exception that happened on ping is still available though
+
 <3> An exception can be hard to relate back to a point in time, so the exception is also available on the audit trail
 

docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc

@@ -81,6 +81,7 @@ var audit = new Auditor(() => Framework.Cluster
 );
 ----
 <1> Always succeed on ping
+
 <2> ...but always fail on calls with a 401 Bad Authentication response
 
 Now, let's make a client call. We'll see that the first audit event is a successful ping
@@ -101,7 +102,9 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> First call results in a successful ping
+
 <2> Second call results in a bad response
+
 <3> The reason for the bad response is Bad Authentication
 
 When a bad authentication response occurs, the client attempts to deserialize the response body returned;
@@ -135,6 +138,7 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> Always return a 401 bad response with a HTML response on client calls
+
 <2> Assert that the response body bytes are null
 
 Now in this example, by turning on `DisableDirectStreaming()` on `ConnectionSettings`, we see the same behaviour exhibited
@@ -169,5 +173,6 @@ audit = await audit.TraceElasticsearchException(
 );
 ----
 <1> Response bytes are set on the response
+
 <2> Assert that the response contains `"nginx/"`
 

docs/client-concepts/connection-pooling/request-overrides/disable-sniff-ping-per-request.asciidoc

@@ -65,8 +65,11 @@ audit = await audit.TraceCalls(
 );
 ----
 <1> disable sniffing
+
 <2> first call is a successful ping
+
 <3> sniff on startup call happens here, on the second call
+
 <4> No sniff on startup again
 
 Now, let's disable pinging on the request 
@@ -90,6 +93,7 @@ audit = await audit.TraceCall(
 );
 ----
 <1> disable ping
+
 <2> No ping after sniffing
 
 Finally, let's demonstrate disabling both sniff and ping on the request 
@@ -111,5 +115,6 @@ audit = await audit.TraceCall(
 );
 ----
 <1> diable ping and sniff
+
 <2> no ping or sniff before the call
 

docs/client-concepts/connection-pooling/round-robin/skip-dead-nodes.asciidoc

@@ -140,7 +140,9 @@ await audit.TraceCalls(
 );
 ----
 <1> The first call goes to 9200 which succeeds
+
 <2> The 2nd call does a ping on 9201 because its used for the first time. It fails so we wrap over to node 9202
+
 <3> The next call goes to 9203 which fails so we should wrap over
 
 A cluster with 2 nodes where the second node fails on ping 
@@ -190,5 +192,6 @@ await audit.TraceCalls(
 );
 ----
 <1> All the calls fail
+
 <2> After all our registered nodes are marked dead we want to sample a single dead node each time to quickly see if the cluster is back up. We do not want to retry all 4 nodes
 

docs/client-concepts/connection-pooling/sniffing/role-detection.asciidoc

@@ -138,6 +138,7 @@ var audit = new Auditor(() => Framework.Cluster
 };
 ----
 <1> Before the sniff, assert we only see three master only nodes
+
 <2> After the sniff, assert we now know about the existence of 20 nodes.
 
 After the sniff has happened on 9200 before the first API call, assert that the subsequent API
@@ -218,7 +219,9 @@ var audit = new Auditor(() => Framework.Cluster
 };
 ----
 <1> for testing simplicity, disable pings
+
 <2> We only want to execute API calls to nodes in rack_one
+
 <3> After sniffing on startup, assert that the pool of nodes that the client will execute API calls against only contains the three nodes that are in `rack_one`
 
 With the cluster set up, assert that the sniff happens on 9200 before the first API call
@@ -295,6 +298,8 @@ await audit.TraceUnexpectedElasticsearchException(new ClientCall
 });
 ----
 <1> The audit trail indicates a sniff for the very first time on startup
+
 <2> The sniff succeeds because the node predicate is ignored when sniffing
+
 <3> when trying to do an actual API call however, the predicate prevents any nodes from being attempted
 

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

@@ -56,7 +56,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]
 ----