updated asciidocs

Author: Mpdreamz

docs/aggregations/writing-aggregations.asciidoc

@@ -144,7 +144,6 @@ 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
 
 Combining multipe `AggregationDescriptor`'s is also possible using the bitwise `&` operator
@@ -212,6 +211,5 @@ 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/connection-pooling/request-overrides/disable-sniff-ping-per-request.asciidoc

@@ -64,9 +64,7 @@ new ClientCall()
 );
 ----
 <1> disable sniffing
-
 <2> first call is a successful ping
-
 <3> sniff on startup call happens here, on the second call
 
 Now, let's disable pinging on the request 
@@ -89,7 +87,6 @@ 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,6 +108,5 @@ audit = await audit.TraceCall(
 );
 ----
 <1> diable ping and sniff
-
 <2> no ping or sniff before the call
 

docs/client-concepts/high-level/inference/field-inference.asciidoc

@@ -500,13 +500,9 @@ class Precedence
 }
 ----
 <1> Even though this property has a NEST property mapping _and_ a `JsonProperty` attribute, We are going to provide a hard rename for it on ConnectionSettings later that should win.
-
 <2> This property has both a NEST attribute and a `JsonProperty`, NEST should win.
-
 <3> We should take the json property into account by itself
-
 <4> This property we are going to special case in our custom serializer to resolve to ask
-
 <5> We are going to register a DefaultFieldNameInferrer on ConnectionSettings that will uppercase all properties.
 
 Here we create a custom serializer that renames any property named `AskSerializer` to `ask`

docs/client-concepts/high-level/inference/indices-paths.asciidoc

@@ -74,9 +74,7 @@ ISearchRequest singleTypedRequest = new SearchDescriptor<Project>().Index(single
 var invalidSingleString = Nest.Indices.Index("name1, name2"); <3>
 ----
 <1> specifying a single index using a string
-
 <2> specifying a single index using a type
-
 <3> an **invalid** single index name
 
 ==== Specifying multiple indices
@@ -100,9 +98,7 @@ ISearchRequest manyTypedRequest = new SearchDescriptor<Project>().Index(manyType
 ((IUrlParameter)manyTypedRequest.Index).GetString(client.ConnectionSettings).Should().Be("project,devs"); <3>
 ----
 <1> specifying multiple indices using strings
-
 <2> specifying multiple indices using types
-
 <3> The index names here come from the Connection Settings passed to `TestClient`. See the documentation on <<index-name-inference, Index Name Inference>> for more details.
 
 ==== Specifying All Indices

docs/client-concepts/low-level/connecting.asciidoc

@@ -314,24 +314,47 @@ therefore **we recommend doing some minimal introspection on the passed in certi
 If running on Core CLR, then a custom connection type must be created by deriving from `HttpConnection` and
 overriding the `CreateHttpClientHandler` method in order to set the `ServerCertificateCustomValidationCallback` property.
 
-=== Overriding default Json.NET behavior
+=== Overriding Json.NET settings
 
 Overriding the default Json.NET behaviour in NEST is an expert behavior but if you need to get to the nitty gritty, this can be really useful.
-First, create a subclass of the `JsonNetSerializer`
+
+The easiest way is to create an instance of `SerializerFactory` that allows you to register a modification callback
+in the constructor
+
+[source,csharp]
+----
+var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
+
+var connectionSettings = new ConnectionSettings(
+    pool,
+    new HttpConnection(),
+    new SerializerFactory((jsonSettings, nestSettings) => jsonSettings.PreserveReferencesHandling = PreserveReferencesHandling.All));
+
+var client = new ElasticClient(connectionSettings);
+----
+
+A more involved and explicit way would be to implement your own JsonNetSerializer subclass.
+
+NOTE: this is subject to change in the next major release. NEST relies heavily on stateful deserializers (that have access to the original
+request) for specialized features such a covariant search results. This requirement leaks into this abstraction.
 
 [source,csharp]
 ----
 public class MyJsonNetSerializer : JsonNetSerializer
 {
-    public MyJsonNetSerializer(IConnectionSettingsValues settings) : base(settings) { }
+    public MyJsonNetSerializer(IConnectionSettingsValues settings)
+        : base(settings, (s, csv) => s.PreserveReferencesHandling = PreserveReferencesHandling.All) <1>
+    {
+        OverwriteDefaultSerializers((s, cvs) => ModifySerializerSettings(s)); <2>
+    }
 
     public int CallToModify { get; set; } = 0;
 
-    protected override void ModifyJsonSerializerSettings(JsonSerializerSettings settings) => ++CallToModify; <1>
+    private void ModifySerializerSettings(JsonSerializerSettings settings) => ++CallToModify;
 
     public int CallToContractConverter { get; set; } = 0;
 
-    protected override IList<Func<Type, JsonConverter>> ContractConverters => new List<Func<Type, JsonConverter>> <2>
+    protected override IList<Func<Type, JsonConverter>> ContractConverters => new List<Func<Type, JsonConverter>> <3>
     {
         t => {
             CallToContractConverter++;
@@ -341,9 +364,11 @@ public class MyJsonNetSerializer : JsonNetSerializer
 
 }
 ----
-<1> Override ModifyJsonSerializerSettings if you need access to `JsonSerializerSettings`
+<1> Call this constructor if you only need access to `JsonSerializerSettings` without local state
+
+<2> Call OverwriteDefaultSerializers if you need access to `JsonSerializerSettings` with local state
 
-<2> You can inject contract resolved converters by implementing the ContractConverters property. This can be much faster then registering them on `JsonSerializerSettings.Converters`
+<3> You can inject contract resolved converters by implementing the ContractConverters property. This can be much faster then registering them on `JsonSerializerSettings.Converters`
 
 You can then register a factory on `ConnectionSettings` to create an instance of your subclass instead.
 This is **_called once per instance_** of ConnectionSettings.

src/Tests/ClientConcepts/LowLevel/Connecting.doc.cs

@@ -315,13 +315,15 @@ public void EasyWay()
 		 *
 		 * NOTE: this is subject to change in the next major release. NEST relies heavily on stateful deserializers (that have access to the original
 		 * request) for specialized features such a covariant search results. This requirement leaks into this abstraction.
+		 *
+		 *
 		 */
 		public class MyJsonNetSerializer : JsonNetSerializer
 		{
 			public MyJsonNetSerializer(IConnectionSettingsValues settings)
-				: base(settings, (s, csv) => s.PreserveReferencesHandling = PreserveReferencesHandling.All) //<1> Call this constructor if you only need access to `JsonSerializerSettings` without state
+				: base(settings, (s, csv) => s.PreserveReferencesHandling = PreserveReferencesHandling.All) //<1> Call this constructor if you only need access to `JsonSerializerSettings` without local state
 			{
-				OverwriteDefaultSerializers((s, cvs) => ModifySerializerSettings(s)); //<2> Call OverwriteDefaultSerializers if you need access to `JsonSerializerSettings` with state
+				OverwriteDefaultSerializers((s, cvs) => ModifySerializerSettings(s)); //<2> Call OverwriteDefaultSerializers if you need access to `JsonSerializerSettings` with local state
 			}
 
 			public int CallToModify { get; set; } = 0;