From 861fed2cd17645393541d4aff780c652990aaa4a Mon Sep 17 00:00:00 2001
From: Smaug123 <patrick+github@patrickstevens.co.uk>
Date: Tue, 6 Feb 2024 20:08:40 +0000
Subject: [PATCH] Add nullness warnings in JsonParse

---
 xml/System.Text.Json.Nodes/JsonNode.xml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/xml/System.Text.Json.Nodes/JsonNode.xml b/xml/System.Text.Json.Nodes/JsonNode.xml
index 0e813003e7e..e23a63cb0a1 100644
--- a/xml/System.Text.Json.Nodes/JsonNode.xml
+++ b/xml/System.Text.Json.Nodes/JsonNode.xml
@@ -2538,7 +2538,7 @@ The underlying value of a <xref:System.Text.Json.Nodes.JsonValue> after deserial
         <param name="reader">The reader to read.</param>
         <param name="nodeOptions">Options to control the behavior.</param>
         <summary>Parses one JSON value (including objects or arrays) from the provided reader.</summary>
-        <returns>The <see cref="T:System.Text.Json.Nodes.JsonNode" /> from the reader.</returns>
+        <returns>The <see cref="T:System.Text.Json.Nodes.JsonNode" /> from the reader, or null if the input represents the null JSON value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -2582,7 +2582,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
         <param name="nodeOptions">Options to control the node behavior after parsing.</param>
         <param name="documentOptions">Options to control the document behavior during parsing.</param>
         <summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a <see cref="T:System.Text.Json.Nodes.JsonNode" />.  The Stream will be read to completion.</summary>
-        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value.</returns>
+        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value, or null if the input represents the null JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.Text.Json.JsonException">
           <paramref name="utf8Json" /> does not represent a valid single JSON value.</exception>
@@ -2620,7 +2620,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
         <param name="nodeOptions">Options to control the node behavior after parsing.</param>
         <param name="documentOptions">Options to control the document behavior during parsing.</param>
         <summary>Parses text representing a single JSON value.</summary>
-        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value.</returns>
+        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value, or null if the input represents the null JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.Text.Json.JsonException">
           <paramref name="utf8Json" /> does not represent a valid single JSON value.</exception>
@@ -2659,7 +2659,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
         <param name="nodeOptions">Options to control the node behavior after parsing.</param>
         <param name="documentOptions">Options to control the document behavior during parsing.</param>
         <summary>Parses text representing a single JSON value.</summary>
-        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value.</returns>
+        <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value, or null if the input represents the null JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="json" /> is <see langword="null" />.</exception>
@@ -2699,7 +2699,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
         <param name="documentOptions">Options to control the document behavior during parsing.</param>
         <param name="cancellationToken">The token to monitor for cancellation requests.</param>
         <summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8 encoded data representing a single JSON value into a <see cref="T:System.Text.Json.Nodes.JsonNode" />.  The stream will be read to completion.</summary>
-        <returns>A <see cref="T:System.Threading.Tasks.Task" /> to produce a <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value.</returns>
+        <returns>A <see cref="T:System.Threading.Tasks.Task" /> to produce either a <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value, or null if the input represents the null JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.Text.Json.JsonException">
           <paramref name="utf8Json" /> does not represent a valid single JSON value.</exception>
@@ -2812,7 +2812,7 @@ The current node is returned if it is a root.
         <param name="options">Options to control the serialization behavior.</param>
         <summary>Converts the current instance to string in JSON format.</summary>
         <returns>JSON representation of current instance.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>Note that <see cref="M:System.Text.Json.Nodes.JsonNode.Parse" /> does not round-trip with this function, because of its behavior on the JSON null value.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ToString">
@@ -2876,3 +2876,4 @@ The current node is returned if it is a root.
     </Member>
   </Members>
 </Type>
+