Add documentation for serialization formatting (#3826)

* Documented that formatting is a hint and added some xmldocs on IElasticsearchSerializer
* XmlDocs for the json serializer extensions

Author: Mpdreamz

src/Elasticsearch.Net/Serialization/ElasticsearchSerializerExtensions.cs

@@ -1,21 +1,30 @@
 using Elasticsearch.Net.Extensions;
-using Elasticsearch.Net.Utf8Json;
 
 namespace Elasticsearch.Net
 {
 	public static class ElasticsearchSerializerExtensions
 	{
+		/// <summary>
+		/// Extension method that serializes an instance of <typeparamref name="T"/> to a byte array.
+		/// </summary>
 		public static byte[] SerializeToBytes<T>(
 			this IElasticsearchSerializer serializer,
 			T data,
-			SerializationFormatting formatting = SerializationFormatting.Indented) =>
+			SerializationFormatting formatting = SerializationFormatting.None) =>
 			SerializeToBytes(serializer, data, RecyclableMemoryStreamFactory.Default, formatting);
 
+		/// <summary>
+		/// Extension method that serializes an instance of <typeparamref name="T"/> to a byte array.
+		/// </summary>
+		/// <param name="memoryStreamFactory">
+		/// A factory yielding MemoryStream instances, defaults to <see cref="RecyclableMemoryStreamFactory"/>
+		/// that yields memory streams backed by pooled byte arrays.
+		/// </param>
 		public static byte[] SerializeToBytes<T>(
 			this IElasticsearchSerializer serializer,
 			T data,
 			IMemoryStreamFactory memoryStreamFactory,
-			SerializationFormatting formatting = SerializationFormatting.Indented
+			SerializationFormatting formatting = SerializationFormatting.None
 		)
 		{
 			memoryStreamFactory = memoryStreamFactory ?? RecyclableMemoryStreamFactory.Default;
@@ -26,17 +35,27 @@ public static byte[] SerializeToBytes<T>(
 			}
 		}
 
+		/// <summary>
+		/// Extension method that serializes an instance of <typeparamref name="T"/> to a string.
+		/// </summary>
 		public static string SerializeToString<T>(
 			this IElasticsearchSerializer serializer,
 			T data,
-			SerializationFormatting formatting = SerializationFormatting.Indented) =>
+			SerializationFormatting formatting = SerializationFormatting.None) =>
 			SerializeToString(serializer, data, RecyclableMemoryStreamFactory.Default, formatting);
 
+		/// <summary>
+		/// Extension method that serializes an instance of <typeparamref name="T"/> to a string.
+		/// </summary>
+		/// <param name="memoryStreamFactory">
+		/// A factory yielding MemoryStream instances, defaults to <see cref="RecyclableMemoryStreamFactory"/>
+		/// that yields memory streams backed by pooled byte arrays.
+		/// </param>
 		public static string SerializeToString<T>(
 			this IElasticsearchSerializer serializer,
 			T data,
 			IMemoryStreamFactory memoryStreamFactory,
-			SerializationFormatting formatting = SerializationFormatting.Indented
+			SerializationFormatting formatting = SerializationFormatting.None
 		)
 		{
 			memoryStreamFactory = memoryStreamFactory ?? RecyclableMemoryStreamFactory.Default;

src/Elasticsearch.Net/Serialization/IElasticsearchSerializer.cs

@@ -7,17 +7,34 @@ namespace Elasticsearch.Net
 {
 	public interface IElasticsearchSerializer
 	{
+		/// <summary> Deserialize <paramref name="stream"/> to an instance of <paramref name="type"/> </summary>
 		object Deserialize(Type type, Stream stream);
 
+		/// <summary> Deserialize <paramref name="stream"/> to an instance of <typeparamref name="T" /></summary>
 		T Deserialize<T>(Stream stream);
 
+		/// <inheritdoc cref="DeserializeAsync"/>
 		Task<object> DeserializeAsync(Type type, Stream stream, CancellationToken cancellationToken = default);
 
+		/// <inheritdoc cref="DeserializeAsync{T}"/>
 		Task<T> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default);
 
-		void Serialize<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.Indented);
+		/// <summary>
+		/// Serialize an instance of <typeparamref name="T"/> to <paramref name="stream"/> using <paramref name="formatting"/>.
+		/// </summary>
+		/// <param name="data">The instance of <typeparamref name="T"/> that we want to serialize</param>
+		/// <param name="stream">The stream to serialize to</param>
+		/// <param name="formatting">
+		/// Formatting hint, note no all implementations of <see cref="IElasticsearchSerializer"/> are able to
+		/// satisfy this hint, including the default serializer that is shipped with 7.0.
+		/// </param>
+		void Serialize<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.None);
 
-		Task SerializeAsync<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.Indented,
+		/// <inheritdoc cref="Serialize{T}"/>
+		Task SerializeAsync<T>(
+			T data,
+			Stream stream,
+			SerializationFormatting formatting = SerializationFormatting.None,
 			CancellationToken cancellationToken = default
 		);
 	}

src/Elasticsearch.Net/Serialization/LowLevelRequestResponseSerializer.cs

@@ -14,32 +14,37 @@ public class LowLevelRequestResponseSerializer : IElasticsearchSerializer
 		public object Deserialize(Type type, Stream stream)
 		{
 			if (stream == null || stream.CanSeek && stream.Length == 0) return Task.FromResult(type.DefaultValue());
+
 			return JsonSerializer.NonGeneric.Deserialize(type, stream, ElasticsearchNetFormatterResolver.Instance);
 		}
 
 		public T Deserialize<T>(Stream stream)
 		{
 			if (stream == null || stream.CanSeek && stream.Length == 0) return default(T);
+
 			return JsonSerializer.Deserialize<T>(stream, ElasticsearchNetFormatterResolver.Instance);
 		}
 
-		public Task<object> DeserializeAsync(Type type, Stream stream, CancellationToken cancellationToken = default(CancellationToken))
+		public Task<object> DeserializeAsync(Type type, Stream stream, CancellationToken cancellationToken = default)
 		{
 			if (stream == null || stream.CanSeek && stream.Length == 0) return Task.FromResult(type.DefaultValue());
+
 			return JsonSerializer.NonGeneric.DeserializeAsync(type, stream, ElasticsearchNetFormatterResolver.Instance);
 		}
 
-		public Task<T> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default(CancellationToken))
+		public Task<T> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default)
 		{
 			if (stream == null || stream.CanSeek && stream.Length == 0) return Task.FromResult(default(T));
+
 			return JsonSerializer.DeserializeAsync<T>(stream, ElasticsearchNetFormatterResolver.Instance);
 		}
 
-		public void Serialize<T>(T data, Stream writableStream, SerializationFormatting formatting = SerializationFormatting.Indented) =>
-			JsonSerializer.Serialize(writableStream, data, ElasticsearchNetFormatterResolver.Instance); // TODO: format indentation
+		public void Serialize<T>(T data, Stream writableStream, SerializationFormatting formatting = SerializationFormatting.None) =>
+			JsonSerializer.Serialize(writableStream, data, ElasticsearchNetFormatterResolver.Instance);
 
 		public Task SerializeAsync<T>(T data, Stream writableStream, SerializationFormatting formatting,
-			CancellationToken cancellationToken = default(CancellationToken)) =>
-			JsonSerializer.SerializeAsync(writableStream, data, ElasticsearchNetFormatterResolver.Instance); // TODO: format indentation
+			CancellationToken cancellationToken = default
+		) =>
+			JsonSerializer.SerializeAsync(writableStream, data, ElasticsearchNetFormatterResolver.Instance);
 	}
 }

src/Elasticsearch.Net/Serialization/SerializationFormatting.cs

@@ -1,5 +1,9 @@
 namespace Elasticsearch.Net
 {
+	/// <summary>
+	/// A hint to <see cref="IElasticsearchSerializer"/> how to format the json.
+	/// Implementation of <see cref="IElasticsearchSerializer"/> might choose to ignore this hint though.
+	/// </summary>
 	public enum SerializationFormatting
 	{
 		None,

src/Serializers/Nest.JsonNetSerializer/ConnectionSettingsAwareSerializerBase.Customization.cs

@@ -35,7 +35,7 @@ public object Deserialize(Type type, Stream stream)
 				return _serializer.Deserialize(jsonTextReader, type);
 		}
 
-		public virtual async Task<T> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default(CancellationToken))
+		public virtual async Task<T> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default)
 		{
 			using (var streamReader = new StreamReader(stream))
 			using (var jsonTextReader = new JsonTextReader(streamReader))
@@ -55,7 +55,7 @@ public object Deserialize(Type type, Stream stream)
 			}
 		}
 
-		public void Serialize<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.Indented)
+		public void Serialize<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.None)
 		{
 			using (var writer = new StreamWriter(stream, ExpectedEncoding, BufferSize, true))
 			using (var jsonWriter = new JsonTextWriter(writer))
@@ -65,8 +65,8 @@ public void Serialize<T>(T data, Stream stream, SerializationFormatting formatti
 			}
 		}
 
-		public Task SerializeAsync<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.Indented,
-			CancellationToken cancellationToken = default(CancellationToken)
+		public Task SerializeAsync<T>(T data, Stream stream, SerializationFormatting formatting = SerializationFormatting.None,
+			CancellationToken cancellationToken = default
 		)
 		{
 			//This makes no sense now but we need the async method on the interface in 6.x so we can start swapping this out