Skip to content

Commit 49481ad

Browse files
committed
Add XML doc comments for public methods on serializer types
1 parent 532c016 commit 49481ad

File tree

3 files changed

+60
-8
lines changed

3 files changed

+60
-8
lines changed

src/Elastic.Clients.Elasticsearch/Serialization/DefaultRequestResponseSerializer.cs

+3-2
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
namespace Elastic.Clients.Elasticsearch.Serialization;
1313

1414
/// <summary>
15-
/// The built in internal serializer that the high level client Elastic.Clients.Elasticsearch uses.
15+
/// The built in internal serializer that the <see cref="ElasticsearchClient"/> uses to serialize
16+
/// built in types.
1617
/// </summary>
1718
internal class DefaultRequestResponseSerializer : SystemTextJsonSerializer
1819
{
@@ -27,7 +28,7 @@ public DefaultRequestResponseSerializer(IElasticsearchClientSettings settings) :
2728
Converters =
2829
{
2930
new KeyValuePairConverterFactory(settings),
30-
new ObjectToInferredTypesConverter(),
31+
new ObjectToInferredTypesConverter(),
3132
new SourceConverterFactory(settings),
3233
new CustomJsonWriterConverterFactory(settings),
3334
new SelfSerializableConverterFactory(settings),

src/Elastic.Clients.Elasticsearch/Serialization/DefaultSourceSerializer.cs

+32-6
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,16 @@
99

1010
namespace Elastic.Clients.Elasticsearch.Serialization;
1111

12+
/// <summary>
13+
/// The built in internal serializer that the <see cref="ElasticsearchClient"/> uses to serialize
14+
/// source document types.
15+
/// </summary>
1216
public class DefaultSourceSerializer : SystemTextJsonSerializer
1317
{
18+
/// <summary>
19+
/// Returns an array of the built in <see cref="JsonConverter"/>s that are used registered with the
20+
/// source serializer by default.
21+
/// </summary>
1422
public static JsonConverter[] DefaultBuiltInConverters => new JsonConverter[]
1523
{
1624
new JsonStringEnumConverter(),
@@ -26,20 +34,31 @@ internal DefaultSourceSerializer(IElasticsearchClientSettings settings) : base(s
2634
Initialize();
2735
}
2836

37+
/// <summary>
38+
/// Constructs a new <see cref="DefaultSourceSerializer"/> instance that accepts an <see cref="Action{T}"/> that can
39+
/// be provided to customize the default <see cref="JsonSerializerOptions"/>.
40+
/// </summary>
41+
/// <param name="settings">An <see cref="IElasticsearchClientSettings"/> instance to which this
42+
/// serializers <see cref="JsonSerializerOptions"/> will be linked.</param>
43+
/// <param name="configureOptions">An <see cref="Action{T}"/> to customize the configuration of the
44+
/// default <see cref="JsonSerializerOptions"/>.</param>
2945
public DefaultSourceSerializer(IElasticsearchClientSettings settings, Action<JsonSerializerOptions> configureOptions) : base(settings)
3046
{
31-
if (configureOptions is null)
32-
throw new ArgumentNullException(nameof(configureOptions));
33-
3447
var options = CreateDefaultJsonSerializerOptions();
3548

36-
configureOptions(options);
49+
configureOptions?.Invoke(options);
3750

3851
_jsonSerializerOptions = options;
3952

4053
Initialize();
41-
}
54+
}
4255

56+
/// <summary>
57+
/// A factory method which returns a new instance of <see cref="JsonSerializerOptions"/> configured with the
58+
/// default configuration applied to for serialization by the <see cref="DefaultSourceSerializer"/>.
59+
/// </summary>
60+
/// <param name="includeDefaultConverters"></param>
61+
/// <returns></returns>
4362
public static JsonSerializerOptions CreateDefaultJsonSerializerOptions(bool includeDefaultConverters = true)
4463
{
4564
var options = new JsonSerializerOptions()
@@ -60,6 +79,13 @@ public static JsonSerializerOptions CreateDefaultJsonSerializerOptions(bool incl
6079
return options;
6180
}
6281

82+
/// <summary>
83+
/// A helper method which applies the default converters for the built in source serializer to an
84+
/// existing <see cref="JsonSerializerOptions"/> instance.
85+
/// </summary>
86+
/// <param name="options">The <see cref="JsonSerializerOptions"/> instance to which to append the default
87+
/// built in <see cref="JsonConverter"/>s.</param>
88+
/// <returns>The <see cref="JsonSerializerOptions"/> instance that was provided as an argument.</returns>
6389
public static JsonSerializerOptions AddDefaultConverters(JsonSerializerOptions options)
6490
{
6591
foreach (var converter in DefaultBuiltInConverters)
@@ -70,5 +96,5 @@ public static JsonSerializerOptions AddDefaultConverters(JsonSerializerOptions o
7096
return options;
7197
}
7298

73-
protected override JsonSerializerOptions CreateJsonSerializerOptions() => _jsonSerializerOptions;
99+
protected sealed override JsonSerializerOptions CreateJsonSerializerOptions() => _jsonSerializerOptions;
74100
}

src/Elastic.Clients.Elasticsearch/Serialization/SystemTextJsonSerializer.cs

+25
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,23 @@ namespace Elastic.Clients.Elasticsearch.Serialization;
1414
/// <summary>
1515
/// An abstract implementation of the transport <see cref="Serializer"/> which serializes
1616
/// using the Microsoft System.Text.Json library.
17+
/// <para>
18+
/// This serializer is <see cref="IElasticsearchClientSettings"/> aware and able to register its
19+
/// <see cref="JsonSerializerOptions"/> in such a way that built in converters for types defined in
20+
/// <c>Elastic.Clients.Elasticsearch</c> can access those settings during serialization.
21+
/// </para>
1722
/// </summary>
1823
public abstract class SystemTextJsonSerializer : Serializer
1924
{
2025
private bool _initialized;
2126

27+
/// <summary>
28+
/// Initializes a new instance of the <see cref="SystemTextJsonSerializer"/> class, linked to an
29+
/// instance of <see cref="IElasticsearchClientSettings"/>.
30+
/// </summary>
31+
/// <param name="settings">An <see cref="IElasticsearchClientSettings"/> instance to which this
32+
/// serializers <see cref="JsonSerializerOptions"/> will be linked.</param>
33+
/// <exception cref="ArgumentNullException"><paramref name="settings"/> is <c>null</c></exception>
2234
public SystemTextJsonSerializer(IElasticsearchClientSettings settings)
2335
{
2436
if (settings is null)
@@ -31,8 +43,17 @@ public SystemTextJsonSerializer(IElasticsearchClientSettings settings)
3143

3244
internal JsonSerializerOptions? IndentedOptions { get; private set; }
3345

46+
/// <summary>
47+
/// Provides access to the <see cref="IElasticsearchClientSettings"/> instance to which this
48+
/// serializers <see cref="JsonSerializerOptions"/> are be linked.
49+
/// </summary>
3450
protected IElasticsearchClientSettings Settings { get; }
3551

52+
/// <summary>
53+
/// A factory method that can create an instance of <see cref="JsonSerializerOptions"/> that will
54+
/// be used when serializing.
55+
/// </summary>
56+
/// <returns></returns>
3657
protected abstract JsonSerializerOptions CreateJsonSerializerOptions();
3758

3859
/// <inheritdoc />
@@ -95,6 +116,10 @@ private static bool TryReturnDefault<T>(Stream stream, out T deserialize)
95116
return stream == null || stream == Stream.Null || (stream.CanSeek && stream.Length == 0);
96117
}
97118

119+
/// <summary>
120+
/// Initializes a serializer instance such that its <see cref="JsonSerializerOptions"/>
121+
/// are populated and linked to the <see cref="IElasticsearchClientSettings"/>.
122+
/// </summary>
98123
protected void Initialize()
99124
{
100125
if (_initialized)

0 commit comments

Comments
 (0)