Skip to content

Update Utf8JsonWriter for null strings, double/single formatting, and consistency. #3143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 10, 2019
Merged

Update Utf8JsonWriter for null strings, double/single formatting, and consistency. #3143

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
adceac6
Update Utf8JsonWriter for null strings, double/single formatting, and
ahsonkhan Sep 9, 2019
c18f9d9
Fix the IBufferWriter<byte> format since using back-ticks didn't work.
ahsonkhan Sep 9, 2019
4440982
Address PR feedback.
ahsonkhan Sep 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion xml/System.Text.Json/JsonReaderOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ By default, the reader throws a <xref:System.Text.Json.JsonException> if it enco

## Remarks

Reading past this depth will throw a <exception cref="T:System.Text.Json.JsonException>.
Reading past this depth will throw a <xref:System.Text.Json.JsonException>.

]]></format>
</remarks>
Expand Down
2 changes: 1 addition & 1 deletion xml/System.Text.Json/JsonWriterOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Also, <xref:System.Text.Json.Utf8JsonWriter> throws an exception if the user att
</ReturnValue>
<Docs>
<summary>Gets or sets the encoder to use when escaping strings, or <see langword="null" /> to use the default encoder.</summary>
<value>The JavaScript character encoding.</value>
<value>The JavaScript character encoder used to override the escaping behavior.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
64 changes: 38 additions & 26 deletions xml/System.Text.Json/Utf8JsonWriter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@

`Utf8JsonWriter` writes the text sequentially with no caching and by default adheres to the [JSON RFC](https://tools.ietf.org/html/rfc8259), with the exception of writing comments.

A method that attempts to write invalid JSON when validation is enabled throws a <xref:System.InvalidOperationException> with a context-specific error message.
A method that attempts to write invalid JSON when validation is enabled throws an <xref:System.InvalidOperationException> with a context-specific error message.

To be able to format the output with indentation and white space OR to skip validation, create an instance of <xref:System.Text.Json.JsonWriterOptions> and pass it in to the writer.
To be able to format the output with indentation and white space, to skip validation, OR to customize the escaping behavior, create an instance of <xref:System.Text.Json.JsonWriterOptions> and pass it in to the writer.

]]></format>
</remarks>
Expand All @@ -56,7 +56,7 @@ To be able to format the output with indentation and white space OR to skip vali
<Docs>
<param name="bufferWriter">The destination for writing JSON text.</param>
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
<param name="options">One of the enumeration values that defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra white space) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding missing dot to @mairaw's suggestion.

Suggested change
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
<param name="options">One of the enumeration values that defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" />. By default, it writes minimized JSON (with no extra white space) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The options isn't an enum though.

<summary>Constructs a new <see cref="T:System.Text.Json.Utf8JsonWriter" /> instance with a specified <see langword="System.Buffers.IBufferWriter&lt;System.Byte&gt;" />.</summary>
<summary>Constructs a new <see cref="T:System.Text.Json.Utf8JsonWriter" /> instance with a specified `IBufferWriter<byte>` to write the output to.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="bufferWriter" /> is <see langword="null" />.</exception>
Expand All @@ -80,7 +80,7 @@ To be able to format the output with indentation and white space OR to skip vali
<Docs>
<param name="utf8Json">The destination for writing JSON text.</param>
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
<param name="options">One of the enumeration values that that defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra white space) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="options">Defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> By default, it writes minimized JSON (with no extra whitespace) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>
<param name="options">One of the enumeration values that that defines the customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" />. By default, it writes minimized JSON (with no extra white space) and validates that the JSON being written is structurally valid according to the JSON RFC.</param>

<summary>Constructs a new <see cref="T:System.Text.Json.Utf8JsonWriter" /> instance with a specified <paramref name="utf8Json" />.</summary>
<summary>Constructs a new <see cref="T:System.Text.Json.Utf8JsonWriter" /> instance with a specified `Stream` to write the output to.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="utf8Json" /> is <see langword="null" />.</exception>
Expand Down Expand Up @@ -322,8 +322,8 @@ In the case of <xref:System.IO.Stream>, this writes the data to the stream and f
<ReturnType>System.Text.Json.JsonWriterOptions</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the custom behavior when writing JSON using this instance, which indicates whether to format the output while writing and whether to skip structural JSON validation.</summary>
<value>An object that defines the behavior of this instance for formatting and validation.</value>
<summary>Gets the custom behavior when writing JSON using this instance, which indicates whether to format the output while writing, whether to skip structural JSON validation, and which characters to escape.</summary>
<value>Defines the behavior of this instance of the writer for formatting, validation, and escaping.</value>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JsonWriterOptions is a struct, not a class.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's my understanding that <value> needs to explain the data type and what it represents. So you could prepend it with "struct instance" for example. Also, as I mentioned in your other PR, in our official docs for "C# objects", it seems that we use "object" to describe a struct instance too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like this? It shouldn't start with a verb here.

Suggested change
<value>Defines the behavior of this instance of the writer for formatting, validation, and escaping.</value>
<value>The custom behavior of this instance of the writer for formatting, validating, and escaping.</value>

<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -383,7 +383,7 @@ The <xref:System.Text.Json.Utf8JsonWriter> will continue to use the original wri

## Remarks

The <xref:System.Text.Json.Utf8JsonWriter> will continue to use the original writer options but now writes to `bufferWriter` as the new destination.
The <xref:System.Text.Json.Utf8JsonWriter> will continue to use the original writer options but now write to `bufferWriter` as the new destination.
Copy link
Member

@jozkee jozkee Sep 9, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did you remove the "s"? Utf8JsonWriter is still a singular.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seemed to make more grammatical sense to my ear.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm on the fence on this one. @rpetrusha can you help?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @jozkee, The Utf8JsonWriter is who's writing. It writes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other option would be to add will write

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tense of write is future, so it should be "write" rather than "writes". As Maira points out, it could also be changed to "will write", and that's fine, but it's not necessary.


]]></format>
</remarks>
Expand Down Expand Up @@ -806,7 +806,7 @@ The property name should already be escaped when the instance of <xref:System.Te
<Parameter Name="utf8Value" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
</Parameters>
<Docs>
<param name="utf8Value">The UTF-8 encoded value to be written as a JSON comment within /*..*/.</param>
<param name="utf8Value">The UTF-8 encoded value to be written as a JSON comment within `/*..*/`.</param>
<summary>Writes a UTF-8 text value as a JSON comment.</summary>
<remarks>
<format><![CDATA[
Expand All @@ -821,7 +821,7 @@ The comment value is not escaped before writing.

-or-

<paramref name="utf8Value" /> contains a comment delimiter (that is, */).</exception>
<paramref name="utf8Value" /> contains a comment delimiter (that is, `*/`).</exception>
Copy link
Contributor

@carlossanlop carlossanlop Sep 9, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From Maira's suggestion above, use <c> if it renders correctly after the build finishes:

Suggested change
<paramref name="utf8Value" /> contains a comment delimiter (that is, `*/`).</exception>
<paramref name="utf8Value" /> contains a comment delimiter (that is, <c>*/</c>).</exception>

I'll leave the suggestions to make it easier to commit them.

</Docs>
</Member>
<Member MemberName="WriteCommentValue">
Expand All @@ -843,7 +843,7 @@ The comment value is not escaped before writing.
<Parameter Name="value" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
</Parameters>
<Docs>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within /*..*/.</param>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within `/*..*/`.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within `/*..*/`.</param>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within <c>/*..*/</c>.</param>

<summary>Writes a UTF-16 text value as a JSON comment.</summary>
<remarks>
<format><![CDATA[
Expand All @@ -854,11 +854,11 @@ The comment value is not escaped before writing.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified value is too large OR.
<exception cref="T:System.ArgumentException">The specified value is too large.

-or-

<paramref name="value" /> contains a comment delimiter (that is, */).</exception>
<paramref name="value" /> contains a comment delimiter (that is, `*/`).</exception>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<paramref name="value" /> contains a comment delimiter (that is, `*/`).</exception>
<paramref name="value" /> contains a comment delimiter (that is, <c>*/</c>).</exception>

</Docs>
</Member>
<Member MemberName="WriteCommentValue">
Expand All @@ -880,7 +880,7 @@ The comment value is not escaped before writing.
<Parameter Name="value" Type="System.String" />
</Parameters>
<Docs>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within /*..*/.</param>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within `/*..*/`.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within `/*..*/`.</param>
<param name="value">The UTF-16 encoded value to be written as a UTF-8 transcoded JSON comment within <c>/*..*/</c>.</param>

<summary>Writes a string text value as a JSON comment.</summary>
<remarks>
<format><![CDATA[
Expand All @@ -895,7 +895,7 @@ The comment value is not escaped before writing.

-or-

<paramref name="value" /> contains a comment delimiter (that is, */).</exception>
<paramref name="value" /> contains a comment delimiter (that is, `*/`).</exception>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<paramref name="value" /> contains a comment delimiter (that is, `*/`).</exception>
<paramref name="value" /> contains a comment delimiter (that is, <c>*/</c>).</exception>

<exception cref="T:System.ArgumentNullException">The <paramref name="value" /> parameter is <see langword="null" />.</exception>
</Docs>
</Member>
Expand Down Expand Up @@ -1167,7 +1167,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or later versions. Uses 'G17' on any other framework.


The property name is escaped before writing.

Expand Down Expand Up @@ -1281,7 +1281,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G9' on any other framework.

The property name is escaped before writing.

Expand Down Expand Up @@ -1443,7 +1443,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.

The property name is escaped before writing.

Expand Down Expand Up @@ -1557,7 +1557,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G9' on any other framework.

The property name is escaped before writing.

Expand Down Expand Up @@ -1720,7 +1720,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.

The property name is escaped before writing.

Expand Down Expand Up @@ -1837,7 +1837,7 @@ The property name is escaped before writing.

## Remarks

Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G9' on any other framework.

The property name is escaped before writing.

Expand Down Expand Up @@ -2001,7 +2001,7 @@ The property name should already be escaped when the instance of <xref:System.Te

## Remarks

Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Double> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.

The property name should already be escaped when the instance of <xref:System.Text.Json.JsonEncodedText> was created.

Expand Down Expand Up @@ -2112,7 +2112,7 @@ The property name should already be escaped when the instance of <xref:System.Te

## Remarks

Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
Writes the <xref:System.Single> using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G9' on any other framework.

The property name should already be escaped when the instance of <xref:System.Text.Json.JsonEncodedText> was created.

Expand Down Expand Up @@ -2264,7 +2264,7 @@ This method writes the <xref:System.Decimal> value using the default <xref:Syste

## Remarks

This method writes the <xref:System.Double> value using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
This method writes the <xref:System.Double> value using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G17' on any other framework.

]]></format>
</remarks>
Expand Down Expand Up @@ -2363,7 +2363,7 @@ This method writes the <xref:System.Int64> value using the default <xref:System.

## Remarks

This method writes the <xref:System.Single> value using the default <xref:System.Buffers.StandardFormat> (that is, 'G').
This method writes the <xref:System.Single> value using the default <xref:System.Buffers.StandardFormat> (that is, 'G') on .NET Core 3.0 or higher. Uses 'G9' on any other framework.

]]></format>
</remarks>
Expand Down Expand Up @@ -2756,7 +2756,7 @@ The property name should already be escaped when the instance of <xref:System.Te
</remarks>
<exception cref="T:System.InvalidOperationException">The depth of the JSON has exceeded the maximum depth of 1000.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I could also do this in a separate PR

Suggested change
<exception cref="T:System.InvalidOperationException">The depth of the JSON has exceeded the maximum depth of 1000.
<exception cref="T:System.InvalidOperationException">The depth of the JSON has exceeded the maximum depth of 1,000.


- or -
-or-

Validation is enabled, and this method would result in writing invalid JSON.</exception>
</Docs>
Expand Down Expand Up @@ -2934,7 +2934,7 @@ The property name should already be escaped when the instance of <xref:System.Te
</remarks>
<exception cref="T:System.InvalidOperationException">The depth of the JSON has exceeded the maximum depth of 1000.

- or -
-or-

Validation is enabled, and this method would result in writing invalid JSON.</exception>
</Docs>
Expand Down Expand Up @@ -3155,6 +3155,8 @@ The property name and value are escaped before writing.

The property name and value are escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.ReadOnlySpan{byte})"/> was called.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressing recent changes around "null:
#3081 (comment)

This PR updated the description around nulls in a few places. We should make sure to capture that:
dotnet/corefx#39344

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.ReadOnlySpan{byte})"/> was called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNull(System.ReadOnlySpan{System.Byte})"> method was called.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not use the langword null here (rather than back-ticks)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're in Markdown land here in the remarks.

This is produced if you use that:
image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I see. Yep, that needs to be fixed. Thanks, @mairaw.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified property name or value is too large.</exception>
Expand Down Expand Up @@ -3415,6 +3417,8 @@ The property name and value are escaped before writing.

The property name and value are escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.ReadOnlySpan{char})"/> was called.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.ReadOnlySpan{char})"/> was called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNull(System.ReadOnlySpan{System.Char})"> method was called.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified property name or value is too large.</exception>
Expand Down Expand Up @@ -3680,6 +3684,8 @@ The property name and value are escaped before writing.

The property name and value are escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(string)"/> were called.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(string)"/> were called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNull(System.String)"> method was called.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified property name or value is too large.</exception>
Expand Down Expand Up @@ -3909,6 +3915,8 @@ The property name should already be escaped when the instance of <xref:System.Te

The value is escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.Text.Json.JsonEncodedText)"/> was called.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.Text.Json.JsonEncodedText)"/> was called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNull(System.Text.Json.JsonEncodedText)"> method was called.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified value is too large.</exception>
Expand Down Expand Up @@ -3947,6 +3955,8 @@ The property name should already be escaped when the instance of <xref:System.Te

The value is escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.Text.Json.JsonEncodedText)"/> was called.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNull(System.Text.Json.JsonEncodedText)"/> was called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNull(System.Text.Json.JsonEncodedText)"> method was called.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified value is too large.</exception>
Expand Down Expand Up @@ -4185,6 +4195,8 @@ The value is escaped before writing.

The value is escaped before writing.

If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNullValue"/> was called.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If <paramref name="value"/> is <see langword="null"/> the JSON null value is written, as if <see cref="WriteNullValue"/> was called.
If `value` is `null`, the JSON null value is written as if the <xref:System.Text.Json.Utf8JsonWriter.WriteNullValue"> method was called.


]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The specified value is too large.</exception>
Expand Down