Further updates to Utf8JsonReader (#3155)

Author: mairaw

xml/System.Text.Json/Utf8JsonReader.xml

@@ -122,7 +122,7 @@ This constructor assumes that the entire JSON payload is contained in `jsonData`
         <param name="jsonData">The UTF-8 encoded JSON text to process.</param>
         <param name="isFinalBlock">
           <see langword="true" /> to indicate that the input sequence contains the entire data to process; <see langword="false" /> to indicate that the input span contains partial data with more data to follow.</param>
-        <param name="state">An object that contains the reader state. If this is the first call to the constructor, pass in a default state. Otherwise, capture the state from the previous instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> by getting the value of the <see cref="P:System.Text.Json.Utf8JsonReader.CurrentState" /> property and pass that back.</param>
+        <param name="state">An object that contains the reader state. If this is the first call to the constructor, pass the default state; otherwise, pass the value of the <see cref="P:System.Text.Json.Utf8JsonReader.CurrentState" /> property from the previous instance of the <see cref="T:System.Text.Json.Utf8JsonReader" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> structure that processes a read-only sequence of UTF-8 encoded text and indicates whether the input contains all the text to process.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -157,7 +157,7 @@ This is the reason why the constructor accepts a <xref:System.Text.Json.JsonRead
         <param name="jsonData">The UTF-8 encoded JSON text to process.</param>
         <param name="isFinalBlock">
           <see langword="true" /> to indicate that the input sequence contains the entire data to process; <see langword="false" /> to indicate that the input span contains partial data with more data to follow.</param>
-        <param name="state">An object that contains the reader state. If it's the first call to the constructor, pass in the default state. Otherwise, capture the state from the previous instance instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> by getting the value of the <see cref="P:System.Text.Json.Utf8JsonReader.CurrentState" /> property and pass that back.</param>
+        <param name="state">An object that contains the reader state. If this is the first call to the constructor, pass the default state; otherwise, pass the value of the <see cref="P:System.Text.Json.Utf8JsonReader.CurrentState" /> property from the previous instance of the <see cref="T:System.Text.Json.Utf8JsonReader" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> structure that processes a read-only span of UTF-8 encoded text and indicates whether the input contains all the text to process.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -377,7 +377,7 @@ The JSON token value represents a number less than <see cref="F:System.Byte.MinV
 
 ## Remarks
 
-This method only creates a DateTime representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
+This method only creates a <xref:System.DateTime> representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
 
  ]]></format>
         </remarks>
@@ -414,7 +414,7 @@ The entire UTF-8 encoded token value cannot be parsed to a <see cref="System.Dat
 
 ## Remarks
 
-This method only creates a DateTimeOffset representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
+This method only creates a <xref:System.DateTimeOffset> representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
 
  ]]></format>
         </remarks>
@@ -1073,7 +1073,15 @@ For comments, this value points to before the first comment delimiter (that is,
         <summary>Tries to parse the current JSON token value from the source as a <see cref="T:System.DateTime" /> and returns a value that indicates whether the operation succeeded. </summary>
         <returns>
           <see langword="true" /> if the entire UTF-8 encoded token value can be successfully parsed to a <see cref="T:System.DateTime" /> value; otherwise, <see langword="false" />.</returns>
-        <remarks>This method only creates a DateTime representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method only creates a <xref:System.DateTime> representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
+
+            ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">The value of the JSON token isn't a <see cref="F:System.Text.Json.JsonTokenType.String" />.</exception>
         <altmember cref="P:System.Text.Json.Utf8JsonReader.TokenType" />
       </Docs>
@@ -1101,7 +1109,15 @@ For comments, this value points to before the first comment delimiter (that is,
         <summary>Tries to parse the current JSON token value from the source as a <see cref="T:System.DateTimeOffset" /> and returns a value that indicates whether the operation succeeded.</summary>
         <returns>
           <see langword="true" /> if the entire UTF-8 encoded token value can be successfully parsed to a <see cref="T:System.DateTimeOffset" /> value; otherwise, <see langword="false" />.</returns>
-        <remarks>This method only creates a DateTimeOffset representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method only creates a <xref:System.DateTimeOffset> representation of JSON strings that conform to the ISO 8601-1 extended format (see [DateTime and DateTimeOffset support in System.Text.Json](~/docs/standard/datetime/system-text-json-support.md)).
+
+            ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">The value of the JSON token isn't a <see cref="F:System.Text.Json.JsonTokenType.String" />.</exception>
         <altmember cref="P:System.Text.Json.Utf8JsonReader.TokenType" />
       </Docs>
@@ -1521,7 +1537,7 @@ Otherwise, the token value must be accessed from <xref:System.Text.Json.Utf8Json
 There is no guarantee that this property will always contain well-formed data. If the input JSON passed in to the `Utf8JsonReader` contains invalid UTF-8 bytes within JSON string tokens, this property will return back those invalid UTF-8 bytes as is.
 Therefore, if the input is untrusted or not previously validated, call <xref:System.Text.Json.Utf8JsonReader.GetString> to get the JSON string token.
 
-Since this property returns the raw bytes, avoid using it for text comparison. Instead call <xref:System.Text.Json.Utf8JsonReader.ValueTextEquals%2A> which will unescape the text if necessary.
+Since this property returns the raw bytes, avoid using it for text comparison. Instead call <xref:System.Text.Json.Utf8JsonReader.ValueTextEquals%2A>, which unescapes the text if necessary.
 
  ]]></format>
         </remarks>
@@ -1564,7 +1580,7 @@ Otherwise, the token value must be accessed from <xref:System.Text.Json.Utf8Json
 There is no guarantee that this property will always contain well-formed data. If the input JSON passed in to the `Utf8JsonReader` contains invalid UTF-8 bytes within JSON string tokens, this property will return back those invalid UTF-8 bytes as is.
 Therefore, if the input is untrusted or not previously validated, call <xref:System.Text.Json.Utf8JsonReader.GetString> to get the JSON string token.
 
-Since this property returns the raw bytes, avoid using it for text comparison. Instead call <xref:System.Text.Json.Utf8JsonReader.ValueTextEquals%2A> which will unescape the text if necessary.
+Since this property returns the raw bytes, avoid using it for text comparison. Instead call <xref:System.Text.Json.Utf8JsonReader.ValueTextEquals%2A> which unescapes the text if necessary.
 
  ]]></format>
         </remarks>