Improvements to generated documentation

Handle simple nested POCO type declarations
Handle encoded generics inside of multline documentation comments
Remove the opening and closing braces of an accessor declaration

Author: russcam

docs/asciidoc/Aggregations/WritingAggregations.doc.asciidoc

@@ -62,20 +62,17 @@ on the request. Using LINQ's `.Aggregate()` method, each function can be applied
 
 [source, csharp]
 ----
+var aggregations = new List<Func<AggregationContainerDescriptor<CommitActivity>, IAggregationContainer>>
 {
-	var aggregations = new List<Func<AggregationContainerDescriptor<CommitActivity>, IAggregationContainer>>
-	{
-		a => a.Average("average_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
-		a => a.Max("max_per_child", avg => avg.Field(p => p.ConfidenceFactor))
-	};
-
-	return s => s
-		.Aggregations(aggs => aggs
-			.Children<CommitActivity>("name_of_child_agg", child => child
-.Aggregations(childAggs =>
-	aggregations.Aggregate(childAggs, (acc, agg) => { agg(acc); return acc; })
-)
+	a => a.Average("average_per_child", avg => avg.Field(p => p.ConfidenceFactor)),
+	a => a.Max("max_per_child", avg => avg.Field(p => p.ConfidenceFactor))
+};
+return s => s
+	.Aggregations(aggs => aggs
+		.Children<CommitActivity>("name_of_child_agg", child => child
+			.Aggregations(childAggs =>
+				aggregations.Aggregate(childAggs, (acc, agg) => { agg(acc); return acc; })
 			)
-		);
-}
+		)
+	);
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/BuildingBlocks/ConnectionPooling.Doc.asciidoc

@@ -2,10 +2,10 @@
 Connection pooling is the internal mechanism that takes care of registering what nodes there are in the cluster and which
 we can use to issue client calls on.
 
-== SingleNodeConnectionPool 
+== SingleNodeConnectionPool
 The simplest of all connection pools, this takes a single `Uri` and uses that to connect to elasticsearch for all the calls
 It doesn't opt in to sniffing and pinging behavior, and will never mark nodes dead or alive. The one `Uri` it holds is always
-ready to go. 
+ready to go.
 
 [source, csharp]
 ----
@@ -15,7 +15,7 @@ pool.Nodes.Should().HaveCount(1);
 var node = pool.Nodes.First();
 node.Uri.Port.Should().Be(9201);
 ----
-This type of pool is hardwired to optout out sniffing
+This type of pool is hardwired to opt out of sniffing
 
 [source, csharp]
 ----
@@ -27,7 +27,7 @@ and pinging
 ----
 pool.SupportsPinging.Should().BeFalse();
 ----
-When you use the low ceremony ElasticClient constructor that takes a single Uri
+When you use the low ceremony ElasticClient constructor that takes a single Uri,
 We default to this SingleNodeConnectionPool 
 
 [source, csharp]
@@ -58,15 +58,15 @@ client = new ElasticClient(new ConnectionSettings(pool));
 ----
 client.ConnectionSettings.ConnectionPool.Should().BeOfType<SingleNodeConnectionPool>();
 ----
-== StaticConnectionPool 
-The static connection pool is great if you have a known small sized cluster and do no want to enable 
+== StaticConnectionPool
+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.
 
 [source, csharp]
 ----
 var uris = Enumerable.Range(9200, 5).Select(p => new Uri("http://localhost:" + p));
 ----
-a connection pool can be seeded using an enumerable of `Uri` 
+a connection pool can be seeded using an enumerable of `Uri`s 
 
 [source, csharp]
 ----
@@ -82,7 +82,7 @@ var nodes = uris.Select(u=>new Node(u));
 ----
 pool = new StaticConnectionPool(nodes);
 ----
-This type of pool is hardwirted to optout out sniffing
+This type of pool is hardwired to opt out of sniffing
 
 [source, csharp]
 ----
@@ -105,9 +105,9 @@ var client = new ElasticClient(new ConnectionSettings(pool));
 ----
 client.ConnectionSettings.ConnectionPool.Should().BeOfType<StaticConnectionPool>();
 ----
-== SniffingConnectionPool 
+== SniffingConnectionPool
 A subclass of StaticConnectionPool that allows itself to be reseeded at run time.
-It comes with a very minor overhead of a ReaderWriterLock to ensure thread safety.
+It comes with a very minor overhead of a `ReaderWriterLockSlim` to ensure thread safety.
 
 [source, csharp]
 ----
@@ -132,19 +132,19 @@ var nodes = uris.Select(u=>new Node(u));
 ----
 pool = new SniffingConnectionPool(nodes);
 ----
-This type of pool is hardwired to opt out of sniffing
+This type of pool is hardwired to opt in to sniffing
 
 [source, csharp]
 ----
 pool.SupportsReseeding.Should().BeTrue();
 ----
-but supports pinging when enabled 
+and pinging 
 
 [source, csharp]
 ----
 pool.SupportsPinging.Should().BeTrue();
 ----
-To create a client using this siffing connection pool pass 
+To create a client using the sniffing connection pool pass 
 the connection pool to the connectionsettings you pass to ElasticClient
 
 [source, csharp]

docs/asciidoc/ClientConcepts/ConnectionPooling/BuildingBlocks/DateTimeProviders.Doc.asciidoc

@@ -1,7 +1,7 @@
 = Date time providers
 
-Not typically something you'll have to pass to the client but all calls `to DateTime.Now` 
-in the client have been abstracted by IDateTimeProvider. This allows us to unit test timeouts and clusterfailover
+Not typically something you'll have to pass to the client but all calls to `System.DateTime.UtcNow`
+in the client have been abstracted by `IDateTimeProvider`. This allows us to unit test timeouts and clusterfailover
 in run time not being bound to wall clock time.
 
 [source, csharp]
@@ -14,8 +14,8 @@ dates are always returned in UTC
 ----
 dateTimeProvider.Now().Should().BeCloseTo(DateTime.UtcNow);
 ----
-Another responsibility of this interface is to calculate the time a node has to taken out of rotation
-based on the number of attempts to revive it. For very advance usecases this might be something of interest
+Another responsibility of this interface is to calculate the time a node has to be taken out of rotation
+based on the number of attempts to revive it. For very advanced use cases, this might be something of interest
 to provide a custom implementation for.
 
 [source, csharp]
@@ -38,8 +38,8 @@ Plotting these defaults looks as followed:
 [[timeout]]
 .Default formula, x-axis time in minutes, y-axis number of attempts to revive
 image::timeoutplot.png[dead timeout]	
-The goal here is that whenever a node is resurected and is found to still be offline we send it
-back to the doghouse for an ever increasingly long period untill we hit a bounded maximum.
+The goal here is that whenever a node is resurrected and is found to still be offline, we send it
+_back to the doghouse_ for an ever increasingly long period, until we hit a bounded maximum.
 
 [source, csharp]
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/BuildingBlocks/KeepingTrackOfNodes.Doc.asciidoc

@@ -1,4 +1,4 @@
-= 
+= Keeping track of nodes
 
 
 [source, csharp]
@@ -23,8 +23,8 @@ Is resurrected is true on first usage, hints to the transport that a ping might
 ----
 node.IsResurrected.Should().BeTrue();
 ----
-When instantiating your connection pool you could switch these to false to initialize the client to 
-a known cluster topology.  
+When instantiating your connection pool you could switch these to false to initialize the client to
+a known cluster topology.
 
 passing a node with a path should be preserved. Sometimes an elasticsearch node lives behind a proxy 
 

docs/asciidoc/ClientConcepts/ConnectionPooling/BuildingBlocks/RequestPipelines.doc.asciidoc

@@ -1,5 +1,5 @@
-== Request pipeline
-Every request is executed in the context of `RequestPipeline` when you are using the default `ITransport` implementation.
+= Request pipeline
+Every request is executed in the context of `RequestPipeline` when using the default `ITransport` implementation.
 
 
 [source, csharp]
@@ -34,7 +34,7 @@ which can be passed to the transport when instantiating a client
 ----
 var transport = new Transport<ConnectionSettings>(settings, requestPipelineFactory, DateTimeProvider.Default, new MemoryStreamFactory());
 ----
-this allows you to have requests executed on your own custom request pipeline 
+this allows you to have requests executed on your own custom request pipeline
 
 [source, csharp]
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/BuildingBlocks/Transports.Doc.asciidoc

@@ -1,18 +1,18 @@
-== Transports
-The ITransport interface can be seen as the motor block of the client. It's interface is deceitfully simple. 
-Its ultimately responsible from translating a client call to a response. If for some reasons you do not agree with the way we wrote
-the internals of the client by implementing a custom ITransport you can circumvent all of it and introduce your own.
+= Transports
+The `ITransport` interface can be seen as the motor block of the client. It's interface is deceitfully simple.
+It's ultimately responsible from translating a client call to a response. If for some reason you do not agree with the way we wrote
+the internals of the client, by implementing a custom `ITransport`, you can circumvent all of it and introduce your own.
 
 
 Transport is generically typed to a type that implements IConnectionConfigurationValues 
 This is the minimum ITransport needs to report back for the client to function.
-e.g in the low level client transport is instantiated like this:
+e.g in the low level client, transport is instantiated like this:
 
 [source, csharp]
 ----
 var lowLevelTransport = new Transport<ConnectionConfiguration>(new ConnectionConfiguration());
 ----
-In the high level client like this. 
+In the high level client like this: 
 
 [source, csharp]
 ----
@@ -23,9 +23,9 @@ var highlevelTransport = new Transport<ConnectionSettings>(new ConnectionSetting
 var connectionPool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
 var inMemoryTransport = new Transport<ConnectionSettings>(new ConnectionSettings(connectionPool, new InMemoryConnection()));
 ----
-The only two methods on ITransport are Request and DoRequestAsync, the default ITransport implementation is responsible for introducing
-many of the building blocks in the client, if these do not work for you can swap them out for your own custom ITransport implementation. 
-If you feel this need report back to us we would love to learn why you'd go down this route!
+The only two methods on `ITransport` are `Request()` and `RequestAsync()`, the default `ITransport` implementation is responsible for introducing
+many of the building blocks in the client, if these do not work for you can swap them out for your own custom `ITransport` implementation. 
+If you feel this need, please let us know as we'd love to learn why you've go down this route!
 
 [source, csharp]
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/Exceptions/UnexpectedExceptions.doc.asciidoc

@@ -1,7 +1,7 @@
-== Unexpected exceptions 
+== Unexpected exceptions
 When a client call throws an exception that the IConnction can not handle, this exception will bubble
 out the client as an UnexpectedElasticsearchClientException, regardless whether the client is configured to throw or not.
-An IConnection is in charge of knowning what exceptions it can recover from or not. The default IConnection that is based on WebRequest can and 
+An IConnection is in charge of knowning what exceptions it can recover from or not. The default IConnection that is based on WebRequest can and
 will recover from WebExceptions but others will be grounds for immediately exiting the pipeline.
 
 [source, csharp]
@@ -33,10 +33,10 @@ e.FailureReason.Should().Be(PipelineFailure.Unexpected);
 e.InnerException.Should().NotBeNull();
 e.InnerException.Message.Should().Be("boom!");
 ----
-Sometimes an unexpected exception happens further down in the pipeline, this is why we 
-wrap them inside an UnexpectedElasticsearchClientException so that information about where 
+Sometimes an unexpected exception happens further down in the pipeline, this is why we
+wrap them inside an UnexpectedElasticsearchClientException so that information about where
 in the pipeline the unexpected exception is not lost, here a call to 9200 fails using a webexception.
-It then falls over to 9201 which throws an hard exception from within IConnection. We assert that we 
+It then falls over to 9201 which throws an hard exception from within IConnection. We assert that we
 can still see the audit trail for the whole coordinated request.
 
 [source, csharp]
@@ -94,28 +94,12 @@ audit = await audit.TraceUnexpectedException(
 	(e) =>
 	{
 		e.FailureReason.Should().Be(PipelineFailure.Unexpected);
-----
-InnerException is the exception that brought the request down 
-
-[source, csharp]
-----
 e.InnerException.Should().NotBeNull();
 		e.InnerException.Message.Should().Be("boom!");
-----
-The hard exception that happened on ping is still available though 
-
-[source, csharp]
-----
 e.SeenExceptions.Should().NotBeEmpty();
 		var pipelineException = e.SeenExceptions.First();
 		pipelineException.FailureReason.Should().Be(PipelineFailure.PingFailure);
 		pipelineException.InnerException.Message.Should().Be("ping exception");
-----
-Seen exception is hard to relate back to a point in time, the exception is also 
-available on the audit trail
-
-[source, csharp]
-----
 var pingException = e.AuditTrail.First(a => a.Event == AuditEvent.PingFailure).Exception;
 		pingException.Should().NotBeNull();
 		pingException.Message.Should().Be("ping exception");

docs/asciidoc/ClientConcepts/ConnectionPooling/Exceptions/UnrecoverableExceptions.doc.asciidoc

@@ -1,8 +1,8 @@
-== Unrecoverable exceptions 
-Unrecoverable exceptions are excepted exceptions that are grounds to exit the client pipeline immediately. 
-By default the client won't throw on any ElasticsearchClientException but return an invalid response. 
+== Unrecoverable exceptions
+Unrecoverable exceptions are excepted exceptions that are grounds to exit the client pipeline immediately.
+By default the client won't throw on any ElasticsearchClientException but return an invalid response.
 You can configure the client to throw using ThrowExceptions() on ConnectionSettings. The following test
-both a client that throws and one that returns an invalid response with an `.OriginalException` exposed 
+both a client that throws and one that returns an invalid response with an `.OriginalException` exposed
 
 [source, csharp]
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/Failover/FallingOver.doc.asciidoc

@@ -1,5 +1,5 @@
 == Fail over
-When using connection pooling and the pool has sufficient nodes a request will be retried if 
+When using connection pooling and the pool has sufficient nodes a request will be retried if
 the call to a node throws an exception or returns a 502 or 503
 
 [source, csharp]
@@ -19,7 +19,7 @@ audit = await audit.TraceCall(
 			);
 ----
 502 Bad Gateway
-Will be treated as an error that requires retrying 
+Will be treated as an error that requires retrying
 
 [source, csharp]
 ----
@@ -38,7 +38,7 @@ audit = await audit.TraceCall(
 			);
 ----
 503 Service Unavailable
-Will be treated as an error that requires retrying 
+Will be treated as an error that requires retrying
 
 [source, csharp]
 ----

docs/asciidoc/ClientConcepts/ConnectionPooling/MaxRetries/RespectsMaxRetry.doc.asciidoc

@@ -27,8 +27,8 @@ audit = await audit.TraceCall(
 				}
 			);
 ----
-When you have a 100 node cluster you might want to ensure a fixed number of retries. 
-Remember that the actual number of requests is initial attempt + set number of retries 
+When you have a 100 node cluster you might want to ensure a fixed number of retries.
+Remember that the actual number of requests is initial attempt + set number of retries
 
 [source, csharp]
 ----
@@ -118,8 +118,8 @@ audit = await audit.TraceCall(
 			);
 ----
 
-This makes setting any retry setting on a single node connection pool a NOOP, this is by design! 
-Connection pooling and connection failover is about trying to fail sanely whilst still utilizing available resources and 
+This makes setting any retry setting on a single node connection pool a NOOP, this is by design!
+Connection pooling and connection failover is about trying to fail sanely whilst still utilizing available resources and
 not giving up on the fail fast principle. It's *NOT* a mechanism for forcing requests to succeed.
 
 [source, csharp]