Skip to content
This repository was archived by the owner on Jan 23, 2023. It is now read-only.

Commit 7b90f41

Browse files
safernsafern
authored
Fix Utf8JsonWriter xml docs (#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
1 parent 6cd505d commit 7b90f41

26 files changed

Lines changed: 426 additions & 460 deletions

‎src/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.Bytes.cs‎

Lines changed: 21 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,10 @@ public sealed partial class Utf8JsonWriter
1313
/// <summary>
1414
/// 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.
1515
/// </summary>
16-
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
17-
/// <param name="bytes">The binary data to be written as a base 64 encoded JSON string as part of the name/value pair.</param>
18-
/// <remarks>
19-
/// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
20-
/// </remarks>
16+
/// <param name="propertyName">The JSON-encoded name of the property to write.</param>
17+
/// <param name="bytes">The Base64-encoded data to write.</param>
2118
/// <exception cref="InvalidOperationException">
22-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
19+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
2320
/// </exception>
2421
public void WriteBase64String(JsonEncodedText propertyName, ReadOnlySpan<byte> bytes)
2522
=> WriteBase64StringHelper(propertyName.EncodedUtf8Bytes, bytes);
@@ -39,37 +36,37 @@ private void WriteBase64StringHelper(ReadOnlySpan<byte> utf8PropertyName, ReadOn
3936
/// <summary>
4037
/// 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.
4138
/// </summary>
42-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
43-
/// <param name="bytes">The binary data to be written as a base 64 encoded JSON string as part of the name/value pair.</param>
44-
/// <remarks>
45-
/// The property name is escaped before writing.
46-
/// </remarks>
39+
/// <param name="propertyName">The name of the property to write.</param>
40+
/// <param name="bytes">The Base64-encoded data to write.</param>
4741
/// <exception cref="ArgumentException">
4842
/// Thrown when the specified property name is too large.
4943
/// </exception>
5044
/// <exception cref="ArgumentNullException">
5145
/// The <paramref name="propertyName"/> parameter is <see langword="null"/>.
5246
/// </exception>
5347
/// <exception cref="InvalidOperationException">
54-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
48+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
5549
/// </exception>
50+
/// <remarks>
51+
/// The property name is escaped before writing.
52+
/// </remarks>
5653
public void WriteBase64String(string propertyName, ReadOnlySpan<byte> bytes)
5754
=> WriteBase64String((propertyName ?? throw new ArgumentNullException(nameof(propertyName))).AsSpan(), bytes);
5855

5956
/// <summary>
6057
/// 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.
6158
/// </summary>
62-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
63-
/// <param name="bytes">The binary data to be written as a base 64 encoded JSON string as part of the name/value pair.</param>
64-
/// <remarks>
65-
/// The property name is escaped before writing.
66-
/// </remarks>
59+
/// <param name="propertyName">The name of the property to write.</param>
60+
/// <param name="bytes">The Base64-encoded data to write.</param>
6761
/// <exception cref="ArgumentException">
6862
/// Thrown when the specified property name is too large.
6963
/// </exception>
7064
/// <exception cref="InvalidOperationException">
71-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
65+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
7266
/// </exception>
67+
/// <remarks>
68+
/// The property name is escaped before writing.
69+
/// </remarks>
7370
public void WriteBase64String(ReadOnlySpan<char> propertyName, ReadOnlySpan<byte> bytes)
7471
{
7572
JsonWriterHelper.ValidatePropertyAndBytes(propertyName, bytes);
@@ -83,17 +80,17 @@ public void WriteBase64String(ReadOnlySpan<char> propertyName, ReadOnlySpan<byte
8380
/// <summary>
8481
/// 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.
8582
/// </summary>
86-
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
87-
/// <param name="bytes">The binary data to be written as a base 64 encoded JSON string as part of the name/value pair.</param>
88-
/// <remarks>
89-
/// The property name is escaped before writing.
90-
/// </remarks>
83+
/// <param name="utf8PropertyName">The UTF-8 encoded name of the property to write.</param>
84+
/// <param name="bytes">The Base64-encoded data to write.</param>
9185
/// <exception cref="ArgumentException">
9286
/// Thrown when the specified property name is too large.
9387
/// </exception>
9488
/// <exception cref="InvalidOperationException">
95-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
89+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
9690
/// </exception>
91+
/// <remarks>
92+
/// The property name is escaped before writing.
93+
/// </remarks>
9794
public void WriteBase64String(ReadOnlySpan<byte> utf8PropertyName, ReadOnlySpan<byte> bytes)
9895
{
9996
JsonWriterHelper.ValidatePropertyAndBytes(utf8PropertyName, bytes);

‎src/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTime.cs‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ public sealed partial class Utf8JsonWriter
1313
/// <summary>
1414
/// Writes the pre-encoded property name and <see cref="DateTime"/> value (as a JSON string) as part of a name/value pair of a JSON object.
1515
/// </summary>
16-
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
17-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
16+
/// <param name="propertyName">The JSON-encoded name of the property to write.</param>
17+
/// <param name="value">The value to write.</param>
1818
/// <exception cref="InvalidOperationException">
19-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
19+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
2020
/// </exception>
2121
/// <remarks>
2222
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
@@ -38,16 +38,16 @@ private void WriteStringHelper(ReadOnlySpan<byte> utf8PropertyName, DateTime val
3838
/// <summary>
3939
/// Writes the property name and <see cref="DateTime"/> value (as a JSON string) as part of a name/value pair of a JSON object.
4040
/// </summary>
41-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
42-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
41+
/// <param name="propertyName">The name of the property to write.</param>
42+
/// <param name="value">The value to write.</param>
4343
/// <exception cref="ArgumentException">
4444
/// Thrown when the specified property name is too large.
4545
/// </exception>
4646
/// <exception cref="ArgumentNullException">
4747
/// The <paramref name="propertyName"/> parameter is <see langword="null"/>.
4848
/// </exception>
4949
/// <exception cref="InvalidOperationException">
50-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
50+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
5151
/// </exception>
5252
/// <remarks>
5353
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
@@ -59,13 +59,13 @@ public void WriteString(string propertyName, DateTime value)
5959
/// <summary>
6060
/// Writes the property name and <see cref="DateTime"/> value (as a JSON string) as part of a name/value pair of a JSON object.
6161
/// </summary>
62-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
63-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
62+
/// <param name="propertyName">The name of the property to write.</param>
63+
/// <param name="value">The value to write.</param>
6464
/// <exception cref="ArgumentException">
6565
/// Thrown when the specified property name is too large.
6666
/// </exception>
6767
/// <exception cref="InvalidOperationException">
68-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
68+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
6969
/// </exception>
7070
/// <remarks>
7171
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
@@ -84,13 +84,13 @@ public void WriteString(ReadOnlySpan<char> propertyName, DateTime value)
8484
/// <summary>
8585
/// Writes the property name and <see cref="DateTime"/> value (as a JSON string) as part of a name/value pair of a JSON object.
8686
/// </summary>
87-
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
88-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
87+
/// <param name="utf8PropertyName">The UTF-8 encoded name of the property to write.</param>
88+
/// <param name="value">The value to write.</param>
8989
/// <exception cref="ArgumentException">
9090
/// Thrown when the specified property name is too large.
9191
/// </exception>
9292
/// <exception cref="InvalidOperationException">
93-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
93+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
9494
/// </exception>
9595
/// <remarks>
9696
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.

‎src/System.Text.Json/src/System/Text/Json/Writer/Utf8JsonWriter.WriteProperties.DateTimeOffset.cs‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,13 @@ public sealed partial class Utf8JsonWriter
1313
/// <summary>
1414
/// Writes the pre-encoded property name and <see cref="DateTimeOffset"/> value (as a JSON string) as part of a name/value pair of a JSON object.
1515
/// </summary>
16-
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
17-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
16+
/// <param name="propertyName">The JSON-encoded name of the property to write.</param>
17+
/// <param name="value">The value to to write.</param>
1818
/// <exception cref="InvalidOperationException">
19-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
19+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
2020
/// </exception>
2121
/// <remarks>
2222
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
23-
/// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
2423
/// </remarks>
2524
public void WriteString(JsonEncodedText propertyName, DateTimeOffset value)
2625
=> WriteStringHelper(propertyName.EncodedUtf8Bytes, value);
@@ -38,16 +37,16 @@ private void WriteStringHelper(ReadOnlySpan<byte> utf8PropertyName, DateTimeOffs
3837
/// <summary>
3938
/// Writes the property name and <see cref="DateTimeOffset"/> value (as a JSON string) as part of a name/value pair of a JSON object.
4039
/// </summary>
41-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
42-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
40+
/// <param name="propertyName">The name of the property to write.</param>
41+
/// <param name="value">The value to to write.</param>
4342
/// <exception cref="ArgumentException">
4443
/// Thrown when the specified property name is too large.
4544
/// </exception>
4645
/// <exception cref="ArgumentNullException">
4746
/// The <paramref name="propertyName"/> parameter is <see langword="null"/>.
4847
/// </exception>
4948
/// <exception cref="InvalidOperationException">
50-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
49+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
5150
/// </exception>
5251
/// <remarks>
5352
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
@@ -59,13 +58,13 @@ public void WriteString(string propertyName, DateTimeOffset value)
5958
/// <summary>
6059
/// Writes the property name and <see cref="DateTimeOffset"/> value (as a JSON string) as part of a name/value pair of a JSON object.
6160
/// </summary>
62-
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
63-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
61+
/// <param name="propertyName">The name of the property to write.</param>
62+
/// <param name="value">The value to to write.</param>
6463
/// <exception cref="ArgumentException">
6564
/// Thrown when the specified property name is too large.
6665
/// </exception>
6766
/// <exception cref="InvalidOperationException">
68-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
67+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
6968
/// </exception>
7069
/// <remarks>
7170
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
@@ -85,12 +84,12 @@ public void WriteString(ReadOnlySpan<char> propertyName, DateTimeOffset value)
8584
/// Writes the property name and <see cref="DateTimeOffset"/> value (as a JSON string) as part of a name/value pair of a JSON object.
8685
/// </summary>
8786
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
88-
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
87+
/// <param name="value">The value to to write.</param>
8988
/// <exception cref="ArgumentException">
9089
/// Thrown when the specified property name is too large.
9190
/// </exception>
9291
/// <exception cref="InvalidOperationException">
93-
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
92+
/// Thrown if this would result in invalid JSON being written (while validation is enabled).
9493
/// </exception>
9594
/// <remarks>
9695
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.

0 commit comments

Comments
 (0)