From 3a41a573b328b9076f4b6bbc7fe06788333eef9c Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Tue, 30 Jul 2019 16:56:09 -0700
Subject: [PATCH 1/3] Automatically port System.Text.Json.JsonSerializer

---
 xml/System.Text.Json/JsonSerializer.xml | 308 +++++++++++++++++-------
 1 file changed, 224 insertions(+), 84 deletions(-)

diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml
index 3b3bfc29204..fadd361f2cc 100644
--- a/xml/System.Text.Json/JsonSerializer.xml
+++ b/xml/System.Text.Json/JsonSerializer.xml
@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides functionality to serialize objects or value types to JSON and deserialize JSON into objects or value types.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -38,12 +38,22 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">To be added.</param>
-        <param name="returnType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">JSON text to parse.</param>
+        <param name="returnType">The type of the object to convert to and return.</param>
+        <param name="options">Options to control the behavior during parsing.</param>
+        <summary>Parse the UTF-8 encoded text representing a single JSON value into a <paramref name="returnType" />.</summary>
+        <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize">
@@ -66,12 +76,31 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="json">To be added.</param>
-        <param name="returnType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="json">The JSON text to parse.</param>
+        <param name="returnType">The type of the object to convert to and return.</param>
+        <param name="options">The options to control the behavior during parsing.</param>
+        <summary>Parses the text representing a single JSON value into a <paramref name="returnType" />.</summary>
+        <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Using a <xref:System.String> is not as efficient as using the
+UTF-8 methods since the implementation natively uses UTF-8.
+
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize">
@@ -94,12 +123,43 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="reader">To be added.</param>
-        <param name="returnType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="reader">The reader to read.</param>
+        <param name="returnType">The type of the object to convert to and return.</param>
+        <param name="options">Options to control the serializer behavior during reading.</param>
+        <summary>Reads one JSON value (including objects or arrays) from the provided reader into a <paramref name="returnType" />.</summary>
+        <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of <xref:reader> is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read> to determine the start of the value.
+
+Upon completion of this method <xref:reader> will be positioned at the final token in the JSON value.  If an exception is thrown the reader is reset to the state it was in when the method was called.
+
+This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.
+
+The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict.
+
+Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth>, <xref:System.Text.Json.JsonReaderOptions.CommentHandling> are used while reading.
+               
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON,or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -125,11 +185,16 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">JSON text to parse.</param>
+        <param name="options">Options to control the behavior during parsing.</param>
+        <summary>Parse the UTF-8 encoded text representing a single JSON value into a <typeparamref name="TValue" />.</summary>
+        <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON,or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -155,11 +220,28 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="json">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="json">JSON text to parse.</param>
+        <param name="options">Options to control the behavior during parsing.</param>
+        <summary>Parse the text representing a single JSON value into a <typeparamref name="TValue" />.</summary>
+        <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Using a <xref:System.String> is not as efficient as using the UTF-8 methods since the implementation natively uses UTF-8.
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -185,11 +267,37 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="reader">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="reader">The reader to read.</param>
+        <param name="options">Options to control the serializer behavior during reading.</param>
+        <summary>Reads one JSON value (including objects or arrays) from the provided reader into a <typeparamref name="TValue" />.</summary>
+        <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of <xref:reader> is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read> to determine the start of the value.
+               
+Upon completion of this method <xref:reader> will be positioned at the final token in the JSON value.  If an exception is thrown the reader is reset to the state it was in when the method was called.
+               
+This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.
+               
+The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict.
+
+Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth>, <xref:System.Text.Json.JsonReaderOptions.CommentHandling> are used while reading.
+               
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
       </Docs>
     </Member>
     <Member MemberName="DeserializeAsync">
@@ -212,13 +320,23 @@
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">To be added.</param>
-        <param name="returnType">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">JSON data to parse.</param>
+        <param name="returnType">The type of the object to convert to and return.</param>
+        <param name="options">Options to control the behavior during reading.</param>
+        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the read operation.</param>
+        <summary>Read the UTF-8 encoded text representing a single JSON value into a <paramref name="returnType" />. The Stream will be read to completion.</summary>
+        <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="DeserializeAsync&lt;TValue&gt;">
@@ -244,12 +362,18 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">JSON data to parse.</param>
+        <param name="options">Options to control the behavior during reading.</param>
+        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the read operation.</param>
+        <summary>Read the UTF-8 encoded text representing a single JSON value into a <typeparamref name="TValue" />.
+            The Stream will be read to completion.</summary>
+        <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Serialize">
@@ -272,12 +396,20 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="value">To be added.</param>
-        <param name="inputType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="value">The value to convert.</param>
+        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <summary>Convert the provided value into a <see cref="T:System.String" />.</summary>
+        <returns>A <see cref="T:System.String" /> representation of the value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Using a <xref:System.String> is not as efficient as using UTF-8 encoding since the implementation internally uses UTF-8. See also <xref:System.Text.Json.JsonSerializer.SerializeToUtf8Bytes(System.Object,System.Type,System.Text.Json.JsonSerializerOptions)> and <xref:System.Text.Json.JsonSerializer.SerializeAsync(System.IO.Stream,System.Object,System.Type,System.Text.Json.JsonSerializerOptions,System.Threading.CancellationToken)>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Serialize">
@@ -302,10 +434,10 @@
       </Parameters>
       <Docs>
         <param name="writer">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="inputType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="value">The value to convert and write.</param>
+        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
+        <param name="options">Options to control the behavior.</param>
+        <summary>Write one JSON value (including objects or arrays) to the provided writer.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -332,11 +464,19 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="value">The value to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <summary>Convert the provided value into a <see cref="T:System.String" />.</summary>
+        <returns>A <see cref="T:System.String" /> representation of the value.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Using a <xref:System.String> is not as efficient as using UTF-8 encoding since the implementation internally uses UTF-8. See also <xref:System.Text.Json.JsonSerializer.SerializeToUtf8Bytes(System.Object,System.Type,System.Text.Json.JsonSerializerOptions)> and <xref:System.Text.Json.JsonSerializer.SerializeAsync(System.IO.Stream,System.Object,System.Type,System.Text.Json.JsonSerializerOptions,System.Threading.CancellationToken)>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Serialize&lt;TValue&gt;">
@@ -363,10 +503,10 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="writer">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="writer">The writer to write.</param>
+        <param name="value">The value to convert and write.</param>
+        <param name="options">Options to control the behavior.</param>
+        <summary>Write one JSON value (including objects or arrays) to the provided writer.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -391,13 +531,13 @@
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="inputType">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">The UTF-8 <see cref="T:System.IO.Stream" /> to write to.</param>
+        <param name="value">The value to convert.</param>
+        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the write operation.</param>
+        <summary>Convert the provided value to UTF-8 encoded JSON text and write it to the <see cref="T:System.IO.Stream" />.</summary>
+        <returns>A task that represents the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -425,12 +565,12 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="cancellationToken">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Json">The UTF-8 <see cref="T:System.IO.Stream" /> to write to.</param>
+        <param name="value">The value to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the write operation.</param>
+        <summary>Convert the provided value to UTF-8 encoded JSON text and write it to the <see cref="T:System.IO.Stream" />.</summary>
+        <returns>A task that represents the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -454,11 +594,11 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="value">To be added.</param>
-        <param name="inputType">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="value">The value to convert.</param>
+        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <summary>Convert the provided value into a <see cref="T:System.Byte" /> array.</summary>
+        <returns>A UTF-8 representation of the value.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -485,10 +625,10 @@
       </Parameters>
       <Docs>
         <typeparam name="TValue">To be added.</typeparam>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="value">The value to convert.</param>
+        <param name="options">Options to control the conversion behavior.</param>
+        <summary>Convert the provided value into a <see cref="T:System.Byte" /> array.</summary>
+        <returns>A UTF-8 representation of the value.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

From 3a4190cbfbea7036ce234a62529bc4555ae8b7ba Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Wed, 31 Jul 2019 16:46:45 -0700
Subject: [PATCH 2/3] Update JsonSerializer.xml

---
 xml/System.Text.Json/JsonSerializer.xml | 232 +++++++++++-------------
 1 file changed, 103 insertions(+), 129 deletions(-)

diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml
index fadd361f2cc..bc785eb8246 100644
--- a/xml/System.Text.Json/JsonSerializer.xml
+++ b/xml/System.Text.Json/JsonSerializer.xml
@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Provides functionality to serialize objects or value types to JSON and deserialize JSON into objects or value types.</summary>
+    <summary>Provides functionality to serialize objects or value types to JSON and to deserialize JSON into objects or value types.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -38,22 +38,14 @@
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">JSON text to parse.</param>
+        <param name="utf8Json">The JSON text to parse.</param>
         <param name="returnType">The type of the object to convert to and return.</param>
         <param name="options">Options to control the behavior during parsing.</param>
-        <summary>Parse the UTF-8 encoded text representing a single JSON value into a <paramref name="returnType" />.</summary>
+        <summary>Parses the UTF-8 encoded text representing a single JSON value into an instance of a specified type.</summary>
         <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
         <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize">
@@ -78,8 +70,8 @@
       <Docs>
         <param name="json">The JSON text to parse.</param>
         <param name="returnType">The type of the object to convert to and return.</param>
-        <param name="options">The options to control the behavior during parsing.</param>
-        <summary>Parses the text representing a single JSON value into a <paramref name="returnType" />.</summary>
+        <param name="options">Options to control the behavior during parsing.</param>
+        <summary>Parses the text representing a single JSON value into an instance of a specified type.</summary>
         <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -93,14 +85,6 @@ UTF-8 methods since the implementation natively uses UTF-8.
         </remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
         <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize">
@@ -126,40 +110,25 @@ UTF-8 methods since the implementation natively uses UTF-8.
         <param name="reader">The reader to read.</param>
         <param name="returnType">The type of the object to convert to and return.</param>
         <param name="options">Options to control the serializer behavior during reading.</param>
-        <summary>Reads one JSON value (including objects or arrays) from the provided reader into a <paramref name="returnType" />.</summary>
+        <summary>Reads one JSON value (including objects or arrays) from the provided reader and converts it into an instance of  a specified type.</summary>
         <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of <xref:reader> is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read> to determine the start of the value.
+If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName?displayProperty=nameWithType> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value.
 
-Upon completion of this method <xref:reader> will be positioned at the final token in the JSON value.  If an exception is thrown the reader is reset to the state it was in when the method was called.
+Upon completion of this method, `reader` will be positioned at the final token in the JSON value.  If an exception is thrown, the reader is reset to the state it was in when the method was called.
 
 This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.
 
-The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict.
-
-Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth>, <xref:System.Text.Json.JsonReaderOptions.CommentHandling> are used while reading.
+The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas?displayProperty=nameWithType>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth?displayProperty=nameWithType>, and <xref:System.Text.Json.JsonReaderOptions.CommentHandling?displayProperty=nameWithType> are used while reading.
                
           ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
         <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON,or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <paramref name="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -184,17 +153,21 @@ Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:Syst
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">JSON text to parse.</param>
+        <typeparam name="TValue">The target type of the UTF-8 encoded text.</typeparam>
+        <param name="utf8Json">The JSON text to parse.</param>
         <param name="options">Options to control the behavior during parsing.</param>
-        <summary>Parse the UTF-8 encoded text representing a single JSON value into a <typeparamref name="TValue" />.</summary>
+        <summary>Parses the UTF-8 encoded text representing a single JSON value into an instance of the type specified by a generic type parameter.</summary>
         <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON,or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid.
+          
+-or-
+
+<typeparamref name="TValue" /> is not compatible with the JSON.
+
+-or-
+
+There is remaining data in the stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -219,10 +192,10 @@ Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:Syst
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="json">JSON text to parse.</param>
+        <typeparam name="TValue">The target type of the JSON value.</typeparam>
+        <param name="json">The JSON text to parse.</param>
         <param name="options">Options to control the behavior during parsing.</param>
-        <summary>Parse the text representing a single JSON value into a <typeparamref name="TValue" />.</summary>
+        <summary>Parses the text representing a single JSON value into an instance of the type specified by a generic type parameter.</summary>
         <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -233,15 +206,15 @@ Using a <xref:System.String> is not as efficient as using the UTF-8 methods sinc
           ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="json" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid.
+          
+-or-
+
+<typeparamref name="TValue" /> is not compatible with the JSON.
+
+-or-
+
+There is remaining data in the stream.</exception>
       </Docs>
     </Member>
     <Member MemberName="Deserialize&lt;TValue&gt;">
@@ -266,38 +239,36 @@ Using a <xref:System.String> is not as efficient as using the UTF-8 methods sinc
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
+        <typeparam name="TValue">The target type of the JSON value.</typeparam>
         <param name="reader">The reader to read.</param>
-        <param name="options">Options to control the serializer behavior during reading.</param>
-        <summary>Reads one JSON value (including objects or arrays) from the provided reader into a <typeparamref name="TValue" />.</summary>
+        <param name="options">Options to control serializer behavior during reading.</param>
+        <summary>Reads one JSON value (including objects or arrays) from the provided reader into an instance of the type specified by a generic type parameter.</summary>
         <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of <xref:reader> is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read> to determine the start of the value.
+If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName?displayProperty=nameWithType> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will be advanced by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value.
                
-Upon completion of this method <xref:reader> will be positioned at the final token in the JSON value.  If an exception is thrown the reader is reset to the state it was in when the method was called.
+Upon completion of this method, `reader` will be positioned at the final token in the JSON value. If an exception is thrown, the reader is reset to the state it was in when the method was called.
                
 This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.
                
-The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict.
-
-Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth>, <xref:System.Text.Json.JsonReaderOptions.CommentHandling> are used while reading.
+The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas?displayProperty=nameWithType>, <xref:System.Text.Json.JsonReader<xref:System.Text.Json.JsonReaderOptions.CommentHandling?displayProperty=nameWithType> are used while reading.
                
           ]]></format>
         </remarks>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
-        <exception cref="T:System.ArgumentException"><paramref name="reader" /> is using unsupported options.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid.
+          
+-or-
+
+<typeparamref name="TValue" /> is not compatible with the JSON.
+
+-or-
+
+There is remaining data in the stream.</exception> 
+        <exception cref="T:System.ArgumentException"><paramref name="reader" /> uses unsupported options.</exception>
       </Docs>
     </Member>
     <Member MemberName="DeserializeAsync">
@@ -320,23 +291,23 @@ Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:Syst
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">JSON data to parse.</param>
+        <param name="utf8Json">The JSON data to parse.</param>
         <param name="returnType">The type of the object to convert to and return.</param>
         <param name="options">Options to control the behavior during reading.</param>
-        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the read operation.</param>
-        <summary>Read the UTF-8 encoded text representing a single JSON value into a <paramref name="returnType" />. The Stream will be read to completion.</summary>
+        <param name="cancellationToken">A cancellation token that may be used to cancel the read operation.</param>
+        <summary>Asynchronously reads the UTF-8 encoded text representing a single JSON value into an instance of a specified type. The stream will be read to completion.</summary>
         <returns>A <paramref name="returnType" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.ArgumentNullException"><paramref name="utf8Json" /> or <paramref name="returnType" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramref name="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid.
+          
+-or-
+
+<typeparamref name="TValue" /> is not compatible with the JSON.
+
+-or-
+
+There is remaining data in the stream.</exception> 
       </Docs>
     </Member>
     <Member MemberName="DeserializeAsync&lt;TValue&gt;">
@@ -361,19 +332,22 @@ Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:Syst
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">JSON data to parse.</param>
+        <typeparam name="TValue">The target type of the JSON value.</typeparam>
+        <param name="utf8Json">The JSON data to parse.</param>
         <param name="options">Options to control the behavior during reading.</param>
-        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the read operation.</param>
-        <summary>Read the UTF-8 encoded text representing a single JSON value into a <typeparamref name="TValue" />.
-            The Stream will be read to completion.</summary>
+        <param name="cancellationToken">A token that may be used to cancel the read operation.</param>
+        <summary>Asynchronously reads the UTF-8 encoded text representing a single JSON value into an instance of a type specified by a generic type parameter. The stream will be read to completion.</summary>
         <returns>A <typeparamref name="TValue" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
-        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid, <typeparamref name="TValue" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
+        <exception cref="T:System.Text.Json.JsonException">The JSON is invalid.
+          
+-or-
+
+<typeparamref name="TValue" /> is not compatible with the JSON.
+
+-or-
+
+There is remaining data in the stream.</exception> 
       </Docs>
     </Member>
     <Member MemberName="Serialize">
@@ -399,8 +373,8 @@ Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas>, <xref:Syst
         <param name="value">The value to convert.</param>
         <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
         <param name="options">Options to control the conversion behavior.</param>
-        <summary>Convert the provided value into a <see cref="T:System.String" />.</summary>
-        <returns>A <see cref="T:System.String" /> representation of the value.</returns>
+        <summary>Converts the value of a specified type into a <see cref="T:System.String" />.</summary>
+        <returns>The string representation of the value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -433,11 +407,11 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <param name="writer">To be added.</param>
+        <param name="writer">The JSON writer.</param>
         <param name="value">The value to convert and write.</param>
-        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
-        <param name="options">Options to control the behavior.</param>
-        <summary>Write one JSON value (including objects or arrays) to the provided writer.</summary>
+        <param name="inputType">The type of <paramref name="value" />.</param>
+        <param name="options">Options to control serialization behavior.</param>
+        <summary>Writes one JSON value (including objects or arrays) of a specified type to the provided writer.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -463,11 +437,11 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
+        <typeparam name="TValue">The type of the value to serialize.</typeparam>
         <param name="value">The value to convert.</param>
-        <param name="options">Options to control the conversion behavior.</param>
-        <summary>Convert the provided value into a <see cref="T:System.String" />.</summary>
-        <returns>A <see cref="T:System.String" /> representation of the value.</returns>
+        <param name="options">Options to control serialization behavior.</param>
+        <summary>Converts the value of a type specified by a generic type parameter into a <see cref="T:System.String" />.</summary>
+        <returns>A string representation of the value.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -502,11 +476,11 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="writer">The writer to write.</param>
+        <typeparam name="TValue">The type of the value to serialize.</typeparam>
+        <param name="writer">A JSON writer.</param>
         <param name="value">The value to convert and write.</param>
-        <param name="options">Options to control the behavior.</param>
-        <summary>Write one JSON value (including objects or arrays) to the provided writer.</summary>
+        <param name="options">Options to control serialization behavior.</param>
+        <summary>Writes one JSON value (including objects or arrays) of a type specified by a generic type parameter to the provided writer.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -531,12 +505,12 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="utf8Json">The UTF-8 <see cref="T:System.IO.Stream" /> to write to.</param>
+        <param name="utf8Json">The UTF-8 stream to write to.</param>
         <param name="value">The value to convert.</param>
-        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
-        <param name="options">Options to control the conversion behavior.</param>
-        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the write operation.</param>
-        <summary>Convert the provided value to UTF-8 encoded JSON text and write it to the <see cref="T:System.IO.Stream" />.</summary>
+        <param name="inputType">The type of the value to convert.</param>
+        <param name="options">Options to control serialization behavior.</param>
+        <param name="cancellationToken">A token that may be used to cancel the write operation.</param>
+        <summary>Asynchronously converts the value of a specified type to UTF-8 encoded JSON text and writes it to the specified stream.</summary>
         <returns>A task that represents the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -564,12 +538,12 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
-        <param name="utf8Json">The UTF-8 <see cref="T:System.IO.Stream" /> to write to.</param>
+        <typeparam name="TValue">The type of the value to serialize.</typeparam>
+        <param name="utf8Json">The UTF-8 stream to write to.</param>
         <param name="value">The value to convert.</param>
-        <param name="options">Options to control the conversion behavior.</param>
-        <param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> which may be used to cancel the write operation.</param>
-        <summary>Convert the provided value to UTF-8 encoded JSON text and write it to the <see cref="T:System.IO.Stream" />.</summary>
+        <param name="options">Options to control serialization behavior.</param>
+        <param name="cancellationToken">A token that may be used to cancel the write operation.</param>
+        <summary>Asynchronously converts a value of a type specified by a generic type parametaer to UTF-8 encoded JSON text and writes it to a stream.</summary>
         <returns>A task that represents the asynchronous write operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -595,9 +569,9 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
       </Parameters>
       <Docs>
         <param name="value">The value to convert.</param>
-        <param name="inputType">The type of the <paramref name="value" /> to convert.</param>
+        <param name="inputType">The type of the value to convert.</param>
         <param name="options">Options to control the conversion behavior.</param>
-        <summary>Convert the provided value into a <see cref="T:System.Byte" /> array.</summary>
+        <summary>Converts a value of the specified type into a UTF8-encoded byte array.</summary>
         <returns>A UTF-8 representation of the value.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -624,13 +598,13 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
         <Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" />
       </Parameters>
       <Docs>
-        <typeparam name="TValue">To be added.</typeparam>
+        <typeparam name="TValue">The type of the value.</typeparam>
         <param name="value">The value to convert.</param>
         <param name="options">Options to control the conversion behavior.</param>
-        <summary>Convert the provided value into a <see cref="T:System.Byte" /> array.</summary>
+        <summary>Converts the value of a type specifed by a generic type parameter into a UTF8-encoded byte array.</summary>
         <returns>A UTF-8 representation of the value.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
\ No newline at end of file
+</Type>

From 19df3f7c9d4160b82c968b77e6947fc282d59ac4 Mon Sep 17 00:00:00 2001
From: Ron Petrusha <ronpet@microsoft.com>
Date: Thu, 1 Aug 2019 08:54:12 -0700
Subject: [PATCH 3/3] Added dropped-out text to fix broken xref.

---
 xml/System.Text.Json/JsonSerializer.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml
index bc785eb8246..72955df3727 100644
--- a/xml/System.Text.Json/JsonSerializer.xml
+++ b/xml/System.Text.Json/JsonSerializer.xml
@@ -255,7 +255,7 @@ Upon completion of this method, `reader` will be positioned at the final token i
                
 This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method.
                
-The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas?displayProperty=nameWithType>, <xref:System.Text.Json.JsonReader<xref:System.Text.Json.JsonReaderOptions.CommentHandling?displayProperty=nameWithType> are used while reading.
+The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonReader> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonReaderOptions.AllowTrailingCommas?displayProperty=nameWithType>, <xref:System.Text.Json.JsonReaderOptions.MaxDepth?displayProperty=nameWithType>, and <xref:System.Text.Json.JsonReaderOptions.CommentHandling?displayProperty=nameWithType> are used while reading.
                
           ]]></format>
         </remarks>