Add nullness warnings in JsonParse

dotnet · Feb 6, 2024 · 2ad44d9 · 2ad44d9
1 parent db29c24
commit 2ad44d9
Showing 1 changed file with 7 additions and 6 deletions.
diff --git 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.JsonParse" /> 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>
+