From daae51dab0acd9975719cf607583397f64a14c0a Mon Sep 17 00:00:00 2001 From: Santiago Fernandez Madero Date: Tue, 16 Jul 2019 14:15:10 -0700 Subject: [PATCH] Fix Utf8JsonWriter xml docs (dotnet/corefx#39092) * Fix Utf8JsonWriter xml docs * PR Feedback * PR Feedback * PR Feedback put back remarks for ROS/string overrides * Remove duplicate remarks * PR Feedback * PR Feedback, i.e. -> that is Commit migrated from https://github.com/dotnet/corefx/commit/7b90f41828abea1d9db6d55403a849c2613d996d --- .../Writer/Utf8JsonWriter.WriteProperties.Bytes.cs | 45 ++-- .../Utf8JsonWriter.WriteProperties.DateTime.cs | 24 +- ...tf8JsonWriter.WriteProperties.DateTimeOffset.cs | 23 +- .../Utf8JsonWriter.WriteProperties.Decimal.cs | 33 ++- .../Utf8JsonWriter.WriteProperties.Double.cs | 33 ++- .../Writer/Utf8JsonWriter.WriteProperties.Float.cs | 33 ++- ...f8JsonWriter.WriteProperties.FormattedNumber.cs | 16 +- .../Writer/Utf8JsonWriter.WriteProperties.Guid.cs | 33 ++- .../Utf8JsonWriter.WriteProperties.Literal.cs | 82 ++++--- .../Utf8JsonWriter.WriteProperties.SignedNumber.cs | 67 +++--- .../Utf8JsonWriter.WriteProperties.String.cs | 249 ++++++++++----------- ...tf8JsonWriter.WriteProperties.UnsignedNumber.cs | 66 +++--- .../Writer/Utf8JsonWriter.WriteValues.Bytes.cs | 10 +- .../Writer/Utf8JsonWriter.WriteValues.Comment.cs | 20 +- .../Writer/Utf8JsonWriter.WriteValues.DateTime.cs | 4 +- .../Utf8JsonWriter.WriteValues.DateTimeOffset.cs | 4 +- .../Writer/Utf8JsonWriter.WriteValues.Decimal.cs | 6 +- .../Writer/Utf8JsonWriter.WriteValues.Double.cs | 4 +- .../Writer/Utf8JsonWriter.WriteValues.Float.cs | 4 +- .../Utf8JsonWriter.WriteValues.FormattedNumber.cs | 6 +- .../Json/Writer/Utf8JsonWriter.WriteValues.Guid.cs | 6 +- .../Writer/Utf8JsonWriter.WriteValues.Literal.cs | 6 +- .../Utf8JsonWriter.WriteValues.SignedNumber.cs | 12 +- .../Writer/Utf8JsonWriter.WriteValues.String.cs | 42 ++-- .../Utf8JsonWriter.WriteValues.UnsignedNumber.cs | 12 +- .../src/System/Text/Json/Writer/Utf8JsonWriter.cs | 46 ++-- 26 files changed, 426 insertions(+), 460 deletions(-) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Bytes.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Bytes.cs index 8304baa..d55076b 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Bytes.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Bytes.cs @@ -13,13 +13,10 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and raw bytes value (as a base 64 encoded JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The binary data to be written as a base 64 encoded JSON string as part of the name/value pair. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. + /// The Base64-encoded data to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteBase64String(JsonEncodedText propertyName, ReadOnlySpan bytes) => WriteBase64StringHelper(propertyName.EncodedUtf8Bytes, bytes); @@ -39,11 +36,8 @@ namespace System.Text.Json /// /// Writes the property name and raw bytes value (as a Base64 encoded JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The binary data to be written as a base 64 encoded JSON string as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. + /// The Base64-encoded data to write. /// /// Thrown when the specified property name is too large. /// @@ -51,25 +45,28 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBase64String(string propertyName, ReadOnlySpan bytes) => WriteBase64String((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), bytes); /// /// Writes the property name and raw bytes value (as a base 64 encoded JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The binary data to be written as a base 64 encoded JSON string as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. + /// The Base64-encoded data to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBase64String(ReadOnlySpan propertyName, ReadOnlySpan bytes) { JsonWriterHelper.ValidatePropertyAndBytes(propertyName, bytes); @@ -83,17 +80,17 @@ namespace System.Text.Json /// /// Writes the property name and raw bytes value (as a base 64 encoded JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The binary data to be written as a base 64 encoded JSON string as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. + /// The Base64-encoded data to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBase64String(ReadOnlySpan utf8PropertyName, ReadOnlySpan bytes) { JsonWriterHelper.ValidatePropertyAndBytes(utf8PropertyName, bytes); diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTime.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTime.cs index fff19bb..9e3db00 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTime.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTime.cs @@ -13,10 +13,10 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000. @@ -38,8 +38,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -47,7 +47,7 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000. @@ -59,13 +59,13 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000. @@ -84,13 +84,13 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON string as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000. diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTimeOffset.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTimeOffset.cs index 6462d89..7893df6 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTimeOffset.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTimeOffset.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000-07:00. - /// The property name should already be escaped when the instance of was created. /// public void WriteString(JsonEncodedText propertyName, DateTimeOffset value) => WriteStringHelper(propertyName.EncodedUtf8Bytes, value); @@ -38,8 +37,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to to write. /// /// Thrown when the specified property name is too large. /// @@ -47,7 +46,7 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000-07:00. @@ -59,13 +58,13 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000-07:00. @@ -85,12 +84,12 @@ namespace System.Text.Json /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON string as part of the name/value pair. + /// The value to to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000-07:00. diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Decimal.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Decimal.cs index 0b8722e..8149596 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Decimal.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Decimal.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'). /// public void WriteNumber(JsonEncodedText propertyName, decimal value) => WriteNumberHelper(propertyName.EncodedUtf8Bytes, value); @@ -38,8 +37,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -47,10 +46,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(string propertyName, decimal value) @@ -59,16 +58,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan propertyName, decimal value) @@ -84,16 +83,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan utf8PropertyName, decimal value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Double.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Double.cs index cd06e83..2066a49 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Double.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Double.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'). /// public void WriteNumber(JsonEncodedText propertyName, double value) => WriteNumberHelper(propertyName.EncodedUtf8Bytes, value); @@ -40,8 +39,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -49,10 +48,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(string propertyName, double value) @@ -61,16 +60,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan propertyName, double value) @@ -87,16 +86,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan utf8PropertyName, double value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Float.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Float.cs index 217d09a..899fd9c 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Float.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Float.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write.. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'). /// public void WriteNumber(JsonEncodedText propertyName, float value) => WriteNumberHelper(propertyName.EncodedUtf8Bytes, value); @@ -40,8 +39,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write.. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -49,10 +48,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(string propertyName, float value) @@ -61,16 +60,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write.. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan propertyName, float value) @@ -87,16 +86,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan utf8PropertyName, float value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.FormattedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.FormattedNumber.cs index 9ed7bf5..1264704 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.FormattedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.FormattedNumber.cs @@ -12,8 +12,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -21,10 +21,10 @@ namespace System.Text.Json /// Thrown when does not represent a valid JSON number. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// internal void WriteNumber(ReadOnlySpan propertyName, ReadOnlySpan utf8FormattedNumber) @@ -42,8 +42,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write.. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -51,10 +51,10 @@ namespace System.Text.Json /// Thrown when does not represent a valid JSON number. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// internal void WriteNumber(ReadOnlySpan utf8PropertyName, ReadOnlySpan utf8FormattedNumber) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Guid.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Guid.cs index afee84c..386f546 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Guid.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Guid.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. /// public void WriteString(JsonEncodedText propertyName, Guid value) => WriteStringHelper(propertyName.EncodedUtf8Bytes, value); @@ -38,8 +37,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -47,10 +46,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. + /// Writes the using the default (that is, 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. /// The property name is escaped before writing. /// public void WriteString(string propertyName, Guid value) @@ -59,16 +58,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. + /// Writes the using the default (that is, 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. /// The property name is escaped before writing. /// public void WriteString(ReadOnlySpan propertyName, Guid value) @@ -84,16 +83,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON string as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. + /// Writes the using the default (that is, 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. /// The property name is escaped before writing. /// public void WriteString(ReadOnlySpan utf8PropertyName, Guid value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Literal.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Literal.cs index d08c468..63a3c45 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Literal.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Literal.cs @@ -12,12 +12,9 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and the JSON literal "null" as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteNull(JsonEncodedText propertyName) { @@ -37,10 +34,7 @@ namespace System.Text.Json /// /// Writes the property name and the JSON literal "null" as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. /// /// Thrown when the specified property name is too large. /// @@ -48,24 +42,27 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteNull(string propertyName) => WriteNull((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan()); /// /// Writes the property name and the JSON literal "null" as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteNull(ReadOnlySpan propertyName) { JsonWriterHelper.ValidateProperty(propertyName); @@ -81,16 +78,16 @@ namespace System.Text.Json /// /// Writes the property name and the JSON literal "null" as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// - /// The property name is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteNull(ReadOnlySpan utf8PropertyName) { JsonWriterHelper.ValidateProperty(utf8PropertyName); @@ -106,13 +103,10 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON literal "true" or "false") as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON literal "true" or "false" as part of the name/value pair. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteBoolean(JsonEncodedText propertyName, bool value) { @@ -131,11 +125,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON literal "true" or "false") as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON literal "true" or "false" as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -143,25 +134,28 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBoolean(string propertyName, bool value) => WriteBoolean((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), value); /// /// Writes the property name and value (as a JSON literal "true" or "false") as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON literal "true" or "false" as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBoolean(ReadOnlySpan propertyName, bool value) { JsonWriterHelper.ValidateProperty(propertyName); @@ -177,17 +171,17 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON literal "true" or "false") as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON literal "true" or "false" as part of the name/value pair. - /// - /// The property name is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteBoolean(ReadOnlySpan utf8PropertyName, bool value) { JsonWriterHelper.ValidateProperty(utf8PropertyName); diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.SignedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.SignedNumber.cs index 5b1360d..04431e6 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.SignedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.SignedNumber.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'), for example: 32767. /// public void WriteNumber(JsonEncodedText propertyName, long value) => WriteNumberHelper(propertyName.EncodedUtf8Bytes, value); @@ -38,8 +37,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -47,10 +46,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// public void WriteNumber(string propertyName, long value) @@ -59,16 +58,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan propertyName, long value) @@ -84,16 +83,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan utf8PropertyName, long value) @@ -109,14 +108,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'), for example: 32767. /// public void WriteNumber(JsonEncodedText propertyName, int value) => WriteNumber(propertyName, (long)value); @@ -124,8 +122,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -133,10 +131,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// public void WriteNumber(string propertyName, int value) @@ -145,17 +143,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. - /// The property name is escaped before writing. + /// Writes the using the default (that is, 'G'), for example: 32767. /// public void WriteNumber(ReadOnlySpan propertyName, int value) => WriteNumber(propertyName, (long)value); @@ -163,16 +160,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// public void WriteNumber(ReadOnlySpan utf8PropertyName, int value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.String.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.String.cs index fee7418..950adb4 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.String.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.String.cs @@ -12,12 +12,9 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name (as a JSON string) as the first part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WritePropertyName(JsonEncodedText propertyName) => WritePropertyNameHelper(propertyName.EncodedUtf8Bytes); @@ -35,10 +32,7 @@ namespace System.Text.Json /// /// Writes the property name (as a JSON string) as the first part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. /// /// Thrown when the specified property name is too large. /// @@ -46,24 +40,27 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WritePropertyName(string propertyName) => WritePropertyName((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan()); /// /// Writes the property name (as a JSON string) as the first part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name is escaped before writing. - /// + /// The name of the property to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WritePropertyName(ReadOnlySpan propertyName) { JsonWriterHelper.ValidateProperty(propertyName); @@ -207,16 +204,16 @@ namespace System.Text.Json /// /// Writes the UTF-8 property name (as a JSON string) as the first part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// - /// The property name is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WritePropertyName(ReadOnlySpan utf8PropertyName) { JsonWriterHelper.ValidateProperty(utf8PropertyName); @@ -362,13 +359,10 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and pre-encoded value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The JSON encoded value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The property name and value should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. + /// The JSON-encoded value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteString(JsonEncodedText propertyName, JsonEncodedText value) => WriteStringHelper(propertyName.EncodedUtf8Bytes, value.EncodedUtf8Bytes); @@ -386,11 +380,8 @@ namespace System.Text.Json /// /// Writes the property name and pre-encoded value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The JSON encoded value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The value should already be escaped when the instance of was created. The property name is escaped before writing. - /// + /// The JSON-encoded name of the property to write. + /// The JSON-encoded value to write. /// /// Thrown when the specified property name is too large. /// @@ -398,16 +389,28 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteString(string propertyName, JsonEncodedText value) => WriteString((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), value); /// /// Writes the property name and string text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. + /// + /// Thrown when the specified property name or value is too large. + /// + /// + /// The parameter is . + /// + /// + /// Thrown if this would result in invalid JSON being written (while validation is enabled). + /// /// /// /// The property name and value is escaped before writing. @@ -417,15 +420,6 @@ namespace System.Text.Json /// as if were called. /// /// - /// - /// Thrown when the specified property name or value is too large. - /// - /// - /// The parameter is . - /// - /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). - /// public void WriteString(string propertyName, string value) { if (propertyName == null) @@ -446,17 +440,17 @@ namespace System.Text.Json /// /// Writes the property name and text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name or value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(ReadOnlySpan propertyName, ReadOnlySpan value) { JsonWriterHelper.ValidatePropertyAndValue(propertyName, value); @@ -470,17 +464,17 @@ namespace System.Text.Json /// /// Writes the UTF-8 property name and UTF-8 text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The UTF-8 encoded value to be written as a JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. + /// The UTF-8 encoded value to write. /// /// Thrown when the specified property name or value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(ReadOnlySpan utf8PropertyName, ReadOnlySpan utf8Value) { JsonWriterHelper.ValidatePropertyAndValue(utf8PropertyName, utf8Value); @@ -494,11 +488,16 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and string text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. + /// + /// Thrown when the specified value is too large. + /// + /// + /// Thrown if this would result in invalid JSON being written (while validation is enabled). + /// /// /// - /// The property name should already be escaped when the instance of was created. /// The value is escaped before writing. /// /// @@ -506,12 +505,6 @@ namespace System.Text.Json /// as if was called. /// /// - /// - /// Thrown when the specified value is too large. - /// - /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). - /// public void WriteString(JsonEncodedText propertyName, string value) { if (value == null) @@ -527,17 +520,17 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The property name should already be escaped when the instance of was created. The value is escaped before writing. - /// + /// The JSON-encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The value is escaped before writing. + /// public void WriteString(JsonEncodedText propertyName, ReadOnlySpan value) => WriteStringHelperEscapeValue(propertyName.EncodedUtf8Bytes, value); @@ -567,11 +560,8 @@ namespace System.Text.Json /// /// Writes the property name and text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name or value is too large. /// @@ -579,25 +569,28 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(string propertyName, ReadOnlySpan value) => WriteString((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), value); /// /// Writes the UTF-8 property name and text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name or value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(ReadOnlySpan utf8PropertyName, ReadOnlySpan value) { JsonWriterHelper.ValidatePropertyAndValue(utf8PropertyName, value); @@ -611,17 +604,17 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and UTF-8 text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The UTF-8 encoded value to be written as a JSON string as part of the name/value pair. - /// - /// The property name should already be escaped when the instance of was created. The value is escaped before writing. - /// + /// The JSON-encoded name of the property to write. + /// The UTF-8 encoded value to write. /// /// Thrown when the specified value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The value is escaped before writing. + /// public void WriteString(JsonEncodedText propertyName, ReadOnlySpan utf8Value) => WriteStringHelperEscapeValue(propertyName.EncodedUtf8Bytes, utf8Value); @@ -651,11 +644,8 @@ namespace System.Text.Json /// /// Writes the property name and UTF-8 text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The UTF-8 encoded value to be written as a JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The name of the property to write. + /// The UTF-8 encoded value to write. /// /// Thrown when the specified property name or value is too large. /// @@ -663,25 +653,28 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(string propertyName, ReadOnlySpan utf8Value) => WriteString((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), utf8Value); /// /// Writes the property name and UTF-8 text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The UTF-8 encoded value to be written as a JSON string as part of the name/value pair. - /// - /// The property name and value is escaped before writing. - /// + /// The name of the property to write. + /// The UTF-8 encoded value to write. /// /// Thrown when the specified property name or value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name and value is escaped before writing. + /// public void WriteString(ReadOnlySpan propertyName, ReadOnlySpan utf8Value) { JsonWriterHelper.ValidatePropertyAndValue(propertyName, utf8Value); @@ -695,17 +688,17 @@ namespace System.Text.Json /// /// Writes the property name and pre-encoded value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The JSON encoded value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The value should already be escaped when the instance of was created. The property name is escaped before writing. - /// + /// The name of the property to write. + /// The JSON-encoded value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteString(ReadOnlySpan propertyName, JsonEncodedText value) => WriteStringHelperEscapeProperty(propertyName, value.EncodedUtf8Bytes); @@ -735,8 +728,14 @@ namespace System.Text.Json /// /// Writes the property name and string text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. + /// The name of the property to write. + /// The value to write. + /// + /// Thrown when the specified property name or value is too large. + /// + /// + /// Thrown if this would result in invalid JSON being written (while validation is enabled). + /// /// /// /// The property name and value are escaped before writing. @@ -746,12 +745,6 @@ namespace System.Text.Json /// as if was called. /// /// - /// - /// Thrown when the specified property name or value is too large. - /// - /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). - /// public void WriteString(ReadOnlySpan propertyName, string value) { if (value == null) @@ -767,17 +760,17 @@ namespace System.Text.Json /// /// Writes the UTF-8 property name and pre-encoded value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The JSON encoded value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. - /// - /// The value should already be escaped when the instance of was created. The property name is escaped before writing. - /// + /// The UTF-8 encoded name of the property to write. + /// The JSON-encoded value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The property name is escaped before writing. + /// public void WriteString(ReadOnlySpan utf8PropertyName, JsonEncodedText value) => WriteStringHelperEscapeProperty(utf8PropertyName, value.EncodedUtf8Bytes); @@ -807,8 +800,14 @@ namespace System.Text.Json /// /// Writes the UTF-8 property name and string text value (as a JSON string) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a UTF-8 transcoded JSON string as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. + /// + /// Thrown when the specified property name or value is too large. + /// + /// + /// Thrown if this would result in invalid JSON being written (while validation is enabled). + /// /// /// /// The property name and value are escaped before writing. @@ -818,12 +817,6 @@ namespace System.Text.Json /// as if was called. /// /// - /// - /// Thrown when the specified property name or value is too large. - /// - /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). - /// public void WriteString(ReadOnlySpan utf8PropertyName, string value) { if (value == null) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.UnsignedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.UnsignedNumber.cs index 29d13cc..dd02237 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.UnsignedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.UnsignedNumber.cs @@ -13,14 +13,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'), for example: 32767. /// [CLSCompliant(false)] public void WriteNumber(JsonEncodedText propertyName, ulong value) @@ -39,8 +38,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -48,10 +47,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] @@ -61,16 +60,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] @@ -87,16 +86,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] @@ -113,14 +112,13 @@ namespace System.Text.Json /// /// Writes the pre-encoded property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The JSON-encoded name of the property to write. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. - /// The property name should already be escaped when the instance of was created. + /// Writes the using the default (that is, 'G'), for example: 32767. /// [CLSCompliant(false)] public void WriteNumber(JsonEncodedText propertyName, uint value) @@ -129,8 +127,8 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// @@ -138,10 +136,10 @@ namespace System.Text.Json /// The parameter is . /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] @@ -151,16 +149,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. - /// The value to be written as a JSON number as part of the name/value pair. + /// The name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] @@ -170,16 +168,16 @@ namespace System.Text.Json /// /// Writes the property name and value (as a JSON number) as part of a name/value pair of a JSON object. /// - /// The UTF-8 encoded property name of the JSON object to be written. - /// The value to be written as a JSON number as part of the name/value pair. + /// The UTF-8 encoded name of the property to write. + /// The value to write. /// /// Thrown when the specified property name is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// The property name is escaped before writing. /// [CLSCompliant(false)] diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Bytes.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Bytes.cs index 06b09a3..6651c44 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Bytes.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Bytes.cs @@ -12,16 +12,16 @@ namespace System.Text.Json /// /// Writes the raw bytes value as base 64 encoded JSON string as an element of a JSON array. /// - /// The binary data to be written as a base 64 encoded JSON string element of a JSON array. - /// - /// The bytes are encoded before writing. - /// + /// The Base64-encoded data to write. /// /// Thrown when the specified value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The bytes are encoded before writing. + /// public void WriteBase64StringValue(ReadOnlySpan bytes) { JsonWriterHelper.ValidateBytes(bytes); diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Comment.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Comment.cs index da0edc4..6b63b19 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Comment.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Comment.cs @@ -16,29 +16,29 @@ namespace System.Text.Json /// /// Writes the string text value (as a JSON comment). /// - /// The value to be written as a UTF-8 transcoded JSON comment within /*..*/. - /// - /// The comment value is not escaped before writing. - /// + /// The value to write as a JSON comment within /*..*/. /// - /// Thrown when the specified value is too large OR if the given string text value contains a comment delimiter (i.e. */). + /// Thrown when the specified value is too large OR if the given string text value contains a comment delimiter (that is, */). /// /// /// The parameter is . /// + /// + /// The comment value is not escaped before writing. + /// public void WriteCommentValue(string value) => WriteCommentValue((value ?? throw new ArgumentNullException(nameof(value))).AsSpan()); /// /// Writes the text value (as a JSON comment). /// - /// The value to be written as a UTF-8 transcoded JSON comment within /*..*/. + /// The value to write as a JSON comment within /*..*/. + /// + /// Thrown when the specified value is too large OR if the given text value contains a comment delimiter (that is, */). + /// /// /// The comment value is not escaped before writing. /// - /// - /// Thrown when the specified value is too large OR if the given text value contains a comment delimiter (i.e. */). - /// public void WriteCommentValue(ReadOnlySpan value) { JsonWriterHelper.ValidateValue(value); @@ -136,7 +136,7 @@ namespace System.Text.Json /// The comment value is not escaped before writing. /// /// - /// Thrown when the specified value is too large OR if the given UTF-8 text value contains a comment delimiter (i.e. */). + /// Thrown when the specified value is too large OR if the given UTF-8 text value contains a comment delimiter (that is, */). /// public void WriteCommentValue(ReadOnlySpan utf8Value) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTime.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTime.cs index ef901b4..93d748f 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTime.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTime.cs @@ -13,9 +13,9 @@ namespace System.Text.Json /// /// Writes the value (as a JSON string) as an element of a JSON array. /// - /// The value to be written as a JSON string as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000. diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTimeOffset.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTimeOffset.cs index 3b02456..97cace1 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTimeOffset.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.DateTimeOffset.cs @@ -14,9 +14,9 @@ namespace System.Text.Json /// /// Writes the value (as a JSON string) as an element of a JSON array. /// - /// The value to be written as a JSON string as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the round-trippable ('O') , for example: 2017-06-12T05:30:45.7680000-07:00. diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Decimal.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Decimal.cs index 65203c8..188d549 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Decimal.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Decimal.cs @@ -13,12 +13,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'). + /// Writes the using the default (that is, 'G'). /// public void WriteNumberValue(decimal value) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Double.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Double.cs index f57240f..7b9658e 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Double.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Double.cs @@ -14,9 +14,9 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the default on .NET Core 3 or higher diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Float.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Float.cs index ae0c7a1..39feb17 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Float.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Float.cs @@ -14,9 +14,9 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// /// Writes the using the default on .NET Core 3 or higher diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.FormattedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.FormattedNumber.cs index 6d260ab..a6d7c08 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.FormattedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.FormattedNumber.cs @@ -12,15 +12,15 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// /// Thrown when does not represent a valid JSON number. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// internal void WriteNumberValue(ReadOnlySpan utf8FormattedNumber) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Guid.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Guid.cs index cb5729d..a44711f 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Guid.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Guid.cs @@ -13,12 +13,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON string) as an element of a JSON array. /// - /// The value to be written as a JSON string as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. + /// Writes the using the default (that is, 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn. /// public void WriteStringValue(Guid value) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Literal.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Literal.cs index 836df56..78cf483 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Literal.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.Literal.cs @@ -12,7 +12,7 @@ namespace System.Text.Json /// Writes the JSON literal "null" as an element of a JSON array. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteNullValue() { @@ -25,9 +25,9 @@ namespace System.Text.Json /// /// Writes the value (as a JSON literal "true" or "false") as an element of a JSON array. /// - /// The value to be written as a JSON literal "true" or "false" as an element of a JSON array. + /// The value write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteBooleanValue(bool value) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.SignedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.SignedNumber.cs index 35438b1..668ef34 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.SignedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.SignedNumber.cs @@ -13,12 +13,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// public void WriteNumberValue(int value) => WriteNumberValue((long)value); @@ -26,12 +26,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// public void WriteNumberValue(long value) { diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.String.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.String.cs index 36e27ad..dd8a04a 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.String.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.String.cs @@ -12,12 +12,9 @@ namespace System.Text.Json /// /// Writes the pre-encoded text value (as a JSON string) as an element of a JSON array. /// - /// The JSON encoded value to be written as a UTF-8 transcoded JSON string element of a JSON array. - /// - /// The value should already be escaped when the instance of was created. - /// + /// The JSON-encoded value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStringValue(JsonEncodedText value) => WriteStringValueHelper(value.EncodedUtf8Bytes); @@ -35,20 +32,21 @@ namespace System.Text.Json /// /// Writes the string text value (as a JSON string) as an element of a JSON array. /// - /// The value to be written as a UTF-8 transcoded JSON string element of a JSON array. + /// The value to write. + /// + /// Thrown when the specified value is too large. + /// + /// + /// Thrown if this would result in invalid JSON being written (while validation is enabled). + /// /// - /// The value is escaped before writing. + /// + /// The value is escaped before writing. /// /// If is the JSON null value is written, /// as if was called. /// /// - /// - /// Thrown when the specified value is too large. - /// - /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). - /// public void WriteStringValue(string value) { if (value == null) @@ -64,16 +62,16 @@ namespace System.Text.Json /// /// Writes the text value (as a JSON string) as an element of a JSON array. /// - /// The value to be written as a UTF-8 transcoded JSON string element of a JSON array. - /// - /// The value is escaped before writing. - /// + /// The value to write. /// /// Thrown when the specified value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The value is escaped before writing. + /// public void WriteStringValue(ReadOnlySpan value) { JsonWriterHelper.ValidateValue(value); @@ -208,15 +206,15 @@ namespace System.Text.Json /// Writes the UTF-8 text value (as a JSON string) as an element of a JSON array. /// /// The UTF-8 encoded value to be written as a JSON string element of a JSON array. - /// - /// The value is escaped before writing. - /// /// /// Thrown when the specified value is too large. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// + /// + /// The value is escaped before writing. + /// public void WriteStringValue(ReadOnlySpan utf8Value) { JsonWriterHelper.ValidateValue(utf8Value); diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.UnsignedNumber.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.UnsignedNumber.cs index f6cec3d..ff499f2 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.UnsignedNumber.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteValues.UnsignedNumber.cs @@ -13,12 +13,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// [CLSCompliant(false)] public void WriteNumberValue(uint value) @@ -27,12 +27,12 @@ namespace System.Text.Json /// /// Writes the value (as a JSON number) as an element of a JSON array. /// - /// The value to be written as a JSON number as an element of a JSON array. + /// The value to write. /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// /// - /// Writes the using the default (i.e. 'G'), for example: 32767. + /// Writes the using the default (that is, 'G'), for example: 32767. /// [CLSCompliant(false)] public void WriteNumberValue(ulong value) diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs index ad421c1..783d7a4 100644 --- a/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs +++ b/src/libraries/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.cs @@ -100,7 +100,7 @@ namespace System.Text.Json /// /// An instance of used as a destination for writing JSON text into. /// Defines the customized behavior of the - /// By default, the writes JSON minimized (i.e. with no extra whitespace) + /// By default, the writes JSON minimized (that is, with no extra whitespace) /// and validates that the JSON being written is structurally valid according to JSON RFC. /// /// Thrown when the instance of that is passed in is null. @@ -131,7 +131,7 @@ namespace System.Text.Json /// /// An instance of used as a destination for writing JSON text into. /// Defines the customized behavior of the - /// By default, the writes JSON minimized (i.e. with no extra whitespace) + /// By default, the writes JSON minimized (that is, with no extra whitespace) /// and validates that the JSON being written is structurally valid according to JSON RFC. /// /// Thrown when the instance of that is passed in is null. @@ -433,7 +433,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartArray() { @@ -446,7 +446,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartObject() { @@ -567,13 +567,10 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON array with a pre-encoded property name as the key. /// - /// The JSON encoded property name of the JSON array to be transcoded and written as UTF-8. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartArray(JsonEncodedText propertyName) { @@ -584,13 +581,10 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON object with a pre-encoded property name as the key. /// - /// The JSON encoded property name of the JSON object to be transcoded and written as UTF-8. - /// - /// The property name should already be escaped when the instance of was created. - /// + /// The JSON-encoded name of the property to write. /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartObject(JsonEncodedText propertyName) { @@ -623,7 +617,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartArray(ReadOnlySpan utf8PropertyName) { @@ -649,7 +643,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartObject(ReadOnlySpan utf8PropertyName) { @@ -719,7 +713,7 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON array with a property name as the key. /// - /// The property name of the JSON array to be transcoded and written as UTF-8. + /// The name of the property to write. /// /// The property name is escaped before writing. /// @@ -731,7 +725,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartArray(string propertyName) => WriteStartArray((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan()); @@ -739,7 +733,7 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON object with a property name as the key. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. + /// The name of the property to write. /// /// The property name is escaped before writing. /// @@ -751,7 +745,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartObject(string propertyName) => WriteStartObject((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan()); @@ -759,7 +753,7 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON array with a property name as the key. /// - /// The property name of the JSON array to be transcoded and written as UTF-8. + /// The name of the property to write. /// /// The property name is escaped before writing. /// @@ -768,7 +762,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartArray(ReadOnlySpan propertyName) { @@ -785,7 +779,7 @@ namespace System.Text.Json /// /// Writes the beginning of a JSON object with a property name as the key. /// - /// The property name of the JSON object to be transcoded and written as UTF-8. + /// The name of the property to write. /// /// The property name is escaped before writing. /// @@ -794,7 +788,7 @@ namespace System.Text.Json /// /// /// Thrown when the depth of the JSON has exceeded the maximum depth of 1000 - /// OR if this would result in an invalid JSON to be written (while validation is enabled). + /// OR if this would result in invalid JSON being written (while validation is enabled). /// public void WriteStartObject(ReadOnlySpan propertyName) { @@ -865,7 +859,7 @@ namespace System.Text.Json /// Writes the end of a JSON array. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteEndArray() { @@ -877,7 +871,7 @@ namespace System.Text.Json /// Writes the end of a JSON object. /// /// - /// Thrown if this would result in an invalid JSON to be written (while validation is enabled). + /// Thrown if this would result in invalid JSON being written (while validation is enabled). /// public void WriteEndObject() { -- 2.7.4