Improve connection pooling docs

This commit improves the connection pooling docs by hiding test assertions from being output in documentation, and linking to sniffing and pinging behaviour docs.

Author: russcam

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

@@ -23,8 +23,7 @@ NEST can use to issue client calls on.
 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`.
+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].
 
 --
 
@@ -60,51 +59,25 @@ your cluster through a single load balancer instance.
 ----
 var uri = new Uri("http://localhost:9201");
 var pool = new SingleNodeConnectionPool(uri);
-pool.Nodes.Should().HaveCount(1);
-var node = pool.Nodes.First();
-node.Uri.Port.Should().Be(9201);
+var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
-This type of pool is hardwired to opt out of reseeding (thus, sniffing) as well as pinging 
-
-[source,csharp]
-----
-pool.SupportsReseeding.Should().BeFalse();
-pool.SupportsPinging.Should().BeFalse();
-----
+This type of pool is hardwired to opt out of reseeding (<<sniffing-behaviour, sniffing>>) as well as <<pinging-behaviour, pinging>> 
 
 When you use the low ceremony `ElasticClient` constructor that takes a single `Uri`,
 internally a `SingleNodeConnectionPool` is used
 
 [source,csharp]
 ----
-var client = new ElasticClient(uri);
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<SingleNodeConnectionPool>();
-----
-
-However we urge that you always pass your connection settings explicitly
-
-[source,csharp]
-----
-client = new ElasticClient(new ConnectionSettings(uri));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<SingleNodeConnectionPool>();
+client = new ElasticClient(uri);
 ----
 
-or even better pass the connection pool explicitly
-
-[source,csharp]
-----
-client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<SingleNodeConnectionPool>();
-----
+However we encourage you to pass connection settings explicitly.
 
 [[cloud-connection-pool]]
 ==== CloudConnectionPool
 
-A specialized subclass of `SingleNodeConnectionPool that accepts a Cloud Id and credentials.
+A specialized subclass of `SingleNodeConnectionPool` that accepts a Cloud Id and credentials.
 When used the client will also pick Elastic Cloud optmized defaults for the connection settings.
 
 A Cloud Id for your cluster can be fetched from your Elastic Cloud cluster administration console.
@@ -115,67 +88,26 @@ A Cloud Id should be in the form of `cluster_name:base_64_data` where `base_64_d
 
 Out of these, only `host_name` and `elasticsearch_uuid` are always available.
 
-[source,csharp]
-----
-string ToBase64(string s) => Convert.ToBase64String(Encoding.UTF8.GetBytes(s));
-/* Here we obviously use a ficticuous Cloud Id so lets create a fake one. */
-
-var hostName = "cloud-endpoint.example";
-var elasticsearchUuid = "3dadf823f05388497ea684236d918a1a";
-var services = $"{hostName}${elasticsearchUuid}$3f26e1609cf54a0f80137a80de560da4";
-var cloudId = $"my_cluster:{ToBase64(services)}";
-
-/*
- * In a real scenario you would be able to copy paste `cloudId`
- *
- * A cloud connection pool always needs credentials as well here opt for basic auth
- */
-var credentials = new BasicAuthenticationCredentials("username", "password");
-var pool = new CloudConnectionPool(cloudId, credentials);
-pool.UsingSsl.Should().BeTrue();
-pool.Nodes.Should().HaveCount(1);
-var node = pool.Nodes.First();
-node.Uri.Port.Should().Be(443);
-node.Uri.Host.Should().Be($"{elasticsearchUuid}.{hostName}");
-node.Uri.Scheme.Should().Be("https");
-----
-
-This type of pool like its parent the `SingleNodeConnectionPool` is hardwired to opt out of
-reseeding (thus, sniffing) as well as pinging
+A cloud connection pool can be created using credentials and a `cloudId`
 
 [source,csharp]
 ----
-pool.SupportsReseeding.Should().BeFalse();
-pool.SupportsPinging.Should().BeFalse();
+var credentials = new BasicAuthenticationCredentials("username", "password"); <1>
+var pool = new CloudConnectionPool(cloudId, credentials); <2>
+var client = new ElasticClient(new ConnectionSettings(pool));
 ----
+<1> a username and password that can access Elasticsearch service on Elastic Cloud
 
-You can also directly create a cloud enabled connection using the clients constructor
+<2> `cloudId` is a value that can be retrieved from the Elastic Cloud web console
 
-[source,csharp]
-----
-var client = new ElasticClient(cloudId, credentials);
-client.ConnectionSettings.ConnectionPool
-    .Should()
-    .BeOfType<CloudConnectionPool>();
-----
+This type of pool, like its parent the `SingleNodeConnectionPool`, is hardwired to opt out of
+reseeding (<<sniffing-behaviour, sniffing>>) as well as <<pinging-behaviour, pinging>>.
 
-However we urge that you always pass your connection settings explicitly
+You can also directly create a cloud enabled connection using the `ElasticClient`'s constructor
 
 [source,csharp]
 ----
-client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool.Should().BeOfType<CloudConnectionPool>();
-
-client.ConnectionSettings.EnableHttpCompression.Should().BeTrue();
-client.ConnectionSettings.BasicAuthenticationCredentials.Should().NotBeNull();
-client.ConnectionSettings.BasicAuthenticationCredentials.Username.Should().Be("username");
-foreach (var id in badCloudIds)
-{
-    Action create = () => new ElasticClient(id, credentials);
-
-    create.ShouldThrow<ArgumentException>()
-        .And.Message.Should().Contain("should be a string in the form of cluster_name:base_64_data");
-}
+client = new ElasticClient(cloudId, credentials);
 ----
 
 [[static-connection-pool]]
@@ -184,17 +116,20 @@ foreach (var id in badCloudIds)
 The static connection pool is great if you have a known small sized cluster and do no want to enable
 sniffing to find out the cluster topology.
 
+Given a collection of `Uri` 
+
 [source,csharp]
 ----
 var uris = Enumerable.Range(9200, 5)
     .Select(port => new Uri($"http://localhost:{port}"));
 ----
 
-a connection pool can be seeded using an enumerable of `Uri` 
+a connection pool can be seeded with this collection 
 
 [source,csharp]
 ----
 var pool = new StaticConnectionPool(uris);
+var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
 Or using an enumerable of `Node` 
@@ -203,33 +138,20 @@ Or using an enumerable of `Node`
 ----
 var nodes = uris.Select(u => new Node(u));
 pool = new StaticConnectionPool(nodes);
+client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
 This type of pool is hardwired to opt out of reseeding
-(and hence sniffing) but supports pinging when enabled
-
-[source,csharp]
-----
-pool.SupportsReseeding.Should().BeFalse();
-pool.SupportsPinging.Should().BeTrue();
-----
-
-To create a client using the static connection pool, pass
-the connection pool to the `ConnectionSettings` you pass to `ElasticClient`
-
-[source,csharp]
-----
-var client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<StaticConnectionPool>();
-----
+(<<sniffing-behaviour, sniffing>>) but supports <<pinging-behaviour, pinging>> when enabled.
 
 [[sniffing-connection-pool]]
 ==== SniffingConnectionPool
 
 A pool derived from `StaticConnectionPool`, a sniffing connection pool allows itself to be reseeded at run time.
 It comes with the very minor overhead of a `ReaderWriterLockSlim` to ensure thread safety.
 
+Given a collection of `Uri` 
+
 [source,csharp]
 ----
 var uris = Enumerable.Range(9200, 5)
@@ -241,36 +163,21 @@ a connection pool can be seeded using an enumerable of `Uri`
 [source,csharp]
 ----
 var pool = new SniffingConnectionPool(uris);
+var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
 Or using an enumerable of `Node`. A major benefit in using nodes is that you can include
-known node roles when seeding which
-NEST can use to favour sniffing on master eligible nodes first,
-and take master only nodes out of rotation for issuing client calls on.
+known node roles when seeding, which NEST can then use to favour particular API requests. For example,
+sniffing on master eligible nodes first, and take master only nodes out of rotation for issuing client calls on.
 
 [source,csharp]
 ----
 var nodes = uris.Select(u=>new Node(u));
 pool = new SniffingConnectionPool(nodes);
+client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
-This type of pool is hardwired to opt in to reseeding (and hence sniffing), and pinging 
-
-[source,csharp]
-----
-pool.SupportsReseeding.Should().BeTrue();
-pool.SupportsPinging.Should().BeTrue();
-----
-
-To create a client using the sniffing connection pool pass
-the connection pool to the `ConnectionSettings` you pass to `ElasticClient`
-
-[source,csharp]
-----
-var client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<SniffingConnectionPool>();
-----
+This type of pool is hardwired to opt in to reseeding (<<sniffing-behaviour, sniffing>>), and <<pinging-behaviour, pinging>> 
 
 [[sticky-connection-pool]]
 ==== StickyConnectionPool
@@ -279,6 +186,8 @@ A type of connection pool that returns the first live node to issue a request ag
 It uses https://msdn.microsoft.com/en-us/library/system.threading.interlocked(v=vs.110).aspx[`System.Threading.Interlocked`]
 to keep an _indexer_ to the last live node in a thread safe manner.
 
+Given a collection of `Uri` 
+
 [source,csharp]
 ----
 var uris = Enumerable.Range(9200, 5)
@@ -290,72 +199,54 @@ a connection pool can be seeded using an enumerable of `Uri`
 [source,csharp]
 ----
 var pool = new StickyConnectionPool(uris);
+var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
-Or using an enumerable of `Node`.
-A major benefit here is you can include known node roles when seeding and
-NEST can use this information to favour sniffing on master eligible nodes first
-and take master only nodes out of rotation for issuing client calls on.
+Or using an enumerable of `Node`, similar to `SniffingConnectionPool`
 
 [source,csharp]
 ----
 var nodes = uris.Select(u=>new Node(u));
 pool = new StickyConnectionPool(nodes);
+client = new ElasticClient(new ConnectionSettings(pool));
 ----
 
-This type of pool is hardwired to opt out of reseeding (and hence sniffing), but does support sniffing
-
-[source,csharp]
-----
-pool.SupportsReseeding.Should().BeFalse();
-pool.SupportsPinging.Should().BeTrue();
-----
-
-To create a client using the sticky connection pool pass
-the connection pool to the `ConnectionSettings` you pass to `ElasticClient`
-
-[source,csharp]
-----
-var client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<StickyConnectionPool>();
-----
+This type of pool is hardwired to opt out of reseeding (<<sniffing-behaviour, sniffing>>), but does support <<pinging-behaviour, pinging>>. 
 
 [[sticky-sniffing-connection-pool]]
 ==== Sticky Sniffing Connection Pool
 
 A type of connection pool that returns the first live node to issue a request against, such that the node is _sticky_ between requests.
-This implementation supports sniffing and sorting so that each instance of your application can favor a node in the same rack based
-on node attributes for instance.
+This implementation supports sniffing and sorting so that each instance of your application can favour a node. For example,
+a node in the same rack, based on node attributes.
+
+Given a collection of `Uri` 
 
 [source,csharp]
 ----
 var uris = Enumerable.Range(9200, 5)
     .Select(port => new Uri($"http://localhost:{port}"));
 ----
 
-a sniffing sorted sticky pool takes a second parameter `Func` takes a Node and returns a weight.
-Nodes will be sorted descending by weight. In the following example we score nodes that are client nodes
-AND in rack_id `rack_one` the highest
+a sniffing sorted sticky pool takes a second parameter, a delegate of `Func<Node, float>`, that takes a Node and returns a weight.
+Nodes will be sorted in descending order by weight. In the following example, nodes are scored so that client nodes
+in rack_id `rack_one` score the highest
 
 [source,csharp]
 ----
-var pool = new StickySniffingConnectionPool(uris, n =>
-    (n.ClientNode ? 10 : 0)
-    + (n.Settings.TryGetValue("node.attr.rack_id", out var rackId)
-            && rackId.ToString() == "rack_one" ? 10 : 0));
+var pool = new StickySniffingConnectionPool(uris, node =>
+{
+    var weight = 0f;
 
-pool.SupportsReseeding.Should().BeTrue();
-pool.SupportsPinging.Should().BeTrue();
-----
+    if (node.ClientNode)
+        weight += 10;
 
-To create a client using the sticky sniffing connection pool pass
-the connection pool to the `ConnectionSettings` you pass to `ElasticClient`
+    if (node.Settings.TryGetValue("node.attr.rack_id", out var rackId) && rackId.ToString() == "rack_one")
+        weight += 10;
+
+    return weight;
+});
 
-[source,csharp]
-----
 var client = new ElasticClient(new ConnectionSettings(pool));
-client.ConnectionSettings.ConnectionPool
-    .Should().BeOfType<StickySniffingConnectionPool>();
 ----