Update doc for exceptions thrown during serialization (#33400)

dotnet · Mar 13, 2020 · 5757764 · 5757764
1 parent 4480bdb
commit 5757764
Show file tree

Hide file tree

Showing 9 changed files with 102 additions and 7 deletions.
diff --git a/...libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Span.cs b/...libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Span.cs
@@ -21,6 +21,10 @@ public static partial class JsonSerializer
         /// <typeparamref name="TValue"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         [return: MaybeNull]
         public static TValue Deserialize<TValue>(ReadOnlySpan<byte> utf8Json, JsonSerializerOptions? options = null)
         {
@@ -43,13 +47,17 @@ public static TValue Deserialize<TValue>(ReadOnlySpan<byte> utf8Json, JsonSerial
         /// <param name="returnType">The type of the object to convert to and return.</param>
         /// <param name="options">Options to control the behavior during parsing.</param>
         /// <exception cref="System.ArgumentNullException">
-        /// Thrown if <paramref name="returnType"/> is null.
+        /// <paramref name="returnType"/> is <see langword="null"/>.
         /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
         /// <paramref name="returnType"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="returnType"/> or its serializable members.
+        /// </exception>
         public static object? Deserialize(ReadOnlySpan<byte> utf8Json, Type returnType, JsonSerializerOptions? options = null)
         {
             if (returnType == null)

diff --git a/...braries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Stream.cs b/...braries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Stream.cs
@@ -23,11 +23,18 @@ public static partial class JsonSerializer
         /// <param name="cancellationToken">
         /// The <see cref="System.Threading.CancellationToken"/> which may be used to cancel the read operation.
         /// </param>
+        /// <exception cref="System.ArgumentNullException">
+        /// <paramref name="utf8Json"/>is <see langword="null"/>.
+        /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
         /// <typeparamref name="TValue"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         public static ValueTask<TValue> DeserializeAsync<TValue>(
             Stream utf8Json,
             JsonSerializerOptions? options = null,
@@ -53,13 +60,17 @@ public static ValueTask<TValue> DeserializeAsync<TValue>(
         /// The <see cref="System.Threading.CancellationToken"/> which may be used to cancel the read operation.
         /// </param>
         /// <exception cref="System.ArgumentNullException">
-        /// Thrown if <paramref name="utf8Json"/> or <paramref name="returnType"/> is null.
+        /// <paramref name="utf8Json"/> or <paramref name="returnType"/> is <see langword="null"/>.
         /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
         /// the <paramref name="returnType"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="returnType"/> or its serializable members.
+        /// </exception>
         public static ValueTask<object?> DeserializeAsync(
             Stream utf8Json,
             Type returnType,

diff --git a/...braries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.String.cs b/...braries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.String.cs
@@ -22,13 +22,17 @@ public static partial class JsonSerializer
         /// <param name="json">JSON text to parse.</param>
         /// <param name="options">Options to control the behavior during parsing.</param>
         /// <exception cref="System.ArgumentNullException">
-        /// Thrown if <paramref name="json"/> is null.
+        /// <paramref name="json"/> is <see langword="null"/>.
         /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
         /// <typeparamref name="TValue"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         /// <remarks>Using a <see cref="string"/> is not as efficient as using the
         /// UTF-8 methods since the implementation natively uses UTF-8.
         /// </remarks>
@@ -51,13 +55,17 @@ public static TValue Deserialize<TValue>(string json, JsonSerializerOptions? opt
         /// <param name="returnType">The type of the object to convert to and return.</param>
         /// <param name="options">Options to control the behavior during parsing.</param>
         /// <exception cref="System.ArgumentNullException">
-        /// Thrown if <paramref name="json"/> or <paramref name="returnType"/> is null.
+        /// <paramref name="json"/> or <paramref name="returnType"/> is <see langword="null"/>.
         /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
         /// the <paramref name="returnType"/> is not compatible with the JSON,
         /// or when there is remaining data in the Stream.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="returnType"/> or its serializable members.
+        /// </exception>
         /// <remarks>Using a <see cref="string"/> is not as efficient as using the
         /// UTF-8 methods since the implementation natively uses UTF-8.
         /// </remarks>

diff --git a/...System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Utf8JsonReader.cs b/...System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Read.Utf8JsonReader.cs
@@ -49,6 +49,10 @@ internal static TValue Deserialize<TValue>(ref Utf8JsonReader reader, JsonSerial
         /// <exception cref="ArgumentException">
         ///   <paramref name="reader"/> is using unsupported options.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         /// <remarks>
         ///   <para>
         ///     If the <see cref="Utf8JsonReader.TokenType"/> property of <paramref name="reader"/>
@@ -95,7 +99,7 @@ public static TValue Deserialize<TValue>(ref Utf8JsonReader reader, JsonSerializ
         /// <param name="returnType">The type of the object to convert to and return.</param>
         /// <param name="options">Options to control the serializer behavior during reading.</param>
         /// <exception cref="ArgumentNullException">
-        /// Thrown if <paramref name="returnType"/> is null.
+        /// <paramref name="returnType"/> is <see langword="null"/>.
         /// </exception>
         /// <exception cref="JsonException">
         /// Thrown when the JSON is invalid,
@@ -105,6 +109,10 @@ public static TValue Deserialize<TValue>(ref Utf8JsonReader reader, JsonSerializ
         /// <exception cref="ArgumentException">
         ///   <paramref name="reader"/> is using unsupported options.
         /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="returnType"/> or its serializable members.
+        /// </exception>
         /// <remarks>
         ///   <para>
         ///     If the <see cref="Utf8JsonReader.TokenType"/> property of <paramref name="reader"/>

diff --git a/...ies/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.ByteArray.cs b/...ies/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.ByteArray.cs
@@ -12,6 +12,10 @@ public static partial class JsonSerializer
         /// <returns>A UTF-8 representation of the value.</returns>
         /// <param name="value">The value to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         public static byte[] SerializeToUtf8Bytes<TValue>(TValue value, JsonSerializerOptions? options = null)
         {
             return WriteCoreBytes<TValue>(value, typeof(TValue), options);
@@ -24,6 +28,16 @@ public static byte[] SerializeToUtf8Bytes<TValue>(TValue value, JsonSerializerOp
         /// <param name="value">The value to convert.</param>
         /// <param name="inputType">The type of the <paramref name="value"/> to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
+        /// <exception cref="ArgumentException">
+        /// <paramref name="inputType"/> is not compatible with <paramref name="value"/>.
+        /// </exception>
+        /// <exception cref="System.ArgumentNullException">
+        /// <paramref name="inputType"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="inputType"/>  or its serializable members.
+        /// </exception>
         public static byte[] SerializeToUtf8Bytes(object? value, Type inputType, JsonSerializerOptions? options = null)
         {
             if (inputType == null)

diff --git a/...raries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Stream.cs b/...raries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Stream.cs
@@ -19,6 +19,13 @@ public static partial class JsonSerializer
         /// <param name="value">The value to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
         /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> which may be used to cancel the write operation.</param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="utf8Json"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         public static Task SerializeAsync<TValue>(Stream utf8Json, TValue value, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)
         {
             if (utf8Json == null)
@@ -36,6 +43,16 @@ public static Task SerializeAsync<TValue>(Stream utf8Json, TValue value, JsonSer
         /// <param name="inputType">The type of the <paramref name="value"/> to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
         /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> which may be used to cancel the write operation.</param>
+        /// <exception cref="ArgumentException">
+        /// <paramref name="inputType"/> is not compatible with <paramref name="value"/>.
+        /// </exception>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="utf8Json"/> or <paramref name="inputType"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="inputType"/>  or its serializable members.
+        /// </exception>
         public static Task SerializeAsync(Stream utf8Json, object? value, Type inputType, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)
         {
             if (utf8Json == null)

diff --git a/...raries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.String.cs b/...raries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.String.cs
@@ -12,6 +12,10 @@ public static partial class JsonSerializer
         /// <returns>A <see cref="string"/> representation of the value.</returns>
         /// <param name="value">The value to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
+        /// </exception>
         /// <remarks>Using a <see cref="string"/> is not as efficient as using UTF-8
         /// encoding since the implementation internally uses UTF-8. See also <see cref="SerializeToUtf8Bytes"/>
         /// and <see cref="SerializeAsync"/>.
@@ -28,6 +32,13 @@ public static string Serialize<TValue>(TValue value, JsonSerializerOptions? opti
         /// <param name="value">The value to convert.</param>
         /// <param name="inputType">The type of the <paramref name="value"/> to convert.</param>
         /// <param name="options">Options to control the conversion behavior.</param>
+        /// <exception cref="ArgumentException">
+        /// <paramref name="inputType"/> is not compatible with <paramref name="value"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="inputType"/>  or its serializable members.
+        /// </exception>
         /// <remarks>Using a <see cref="string"/> is not as efficient as using UTF-8
         /// encoding since the implementation internally uses UTF-8. See also <see cref="SerializeToUtf8Bytes"/>
         /// and <see cref="SerializeAsync"/>.

diff --git a/...ystem.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Utf8JsonWriter.cs b/...ystem.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Utf8JsonWriter.cs
@@ -32,7 +32,11 @@ internal static void Serialize<T>(Utf8JsonWriter writer, T value, JsonSerializer
         /// <param name="value">The value to convert and write.</param>
         /// <param name="options">Options to control the behavior.</param>
         /// <exception cref="ArgumentNullException">
-        ///   <paramref name="writer"/> is null.
+        ///   <paramref name="writer"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <typeparamref name="TValue"/> or its serializable members.
         /// </exception>
         public static void Serialize<TValue>(Utf8JsonWriter writer, TValue value, JsonSerializerOptions? options = null)
         {
@@ -46,8 +50,15 @@ public static void Serialize<TValue>(Utf8JsonWriter writer, TValue value, JsonSe
         /// <param name="value">The value to convert and write.</param>
         /// <param name="inputType">The type of the <paramref name="value"/> to convert.</param>
         /// <param name="options">Options to control the behavior.</param>
+        /// <exception cref="ArgumentException">
+        /// <paramref name="inputType"/> is not compatible with <paramref name="value"/>.
+        /// </exception>
         /// <exception cref="ArgumentNullException">
-        ///   <paramref name="writer"/> is null.
+        /// <paramref name="writer"/> or <paramref name="inputType"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="inputType"/> or its serializable members.
         /// </exception>
         public static void Serialize(Utf8JsonWriter writer, object? value, Type inputType, JsonSerializerOptions? options = null)
         {

diff --git a/...s/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializerOptions.Converters.cs b/...s/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializerOptions.Converters.cs
@@ -114,6 +114,13 @@ internal JsonConverter DetermineConverter(Type? parentClassType, Type runtimePro
         /// <returns>
         /// The converter for the given type.
         /// </returns>
+        /// <exception cref="InvalidOperationException">
+        /// The configured <see cref="JsonConverter"/> for <paramref name="typeToConvert"/> returned an invalid converter.
+        /// </exception>
+        /// <exception cref="NotSupportedException">
+        /// There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter"/>
+        /// for <paramref name="typeToConvert"/> or its serializable members.
+        /// </exception>
         public JsonConverter GetConverter(Type typeToConvert)
         {
             if (_converters.TryGetValue(typeToConvert, out JsonConverter? converter))