feedback

xml/System.Text.Json/JsonCommentHandling.xml

@@ -13,7 +13,7 @@
     <BaseTypeName>System.Enum</BaseTypeName>
   </Base>
   <Docs>
-    <summary>Defines how the <see cref="T:System.Text.Json.Utf8JsonReader" /> object handles comments.</summary>
+    <summary>Defines how the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct handles comments.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

xml/System.Text.Json/JsonReaderOptions.xml

@@ -34,7 +34,7 @@
         <ReturnType>System.Text.Json.JsonCommentHandling</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets how the <see cref="T:System.Text.Json.Utf8JsonReader" /> object handles comments when reading through the JSON data.</summary>
+        <summary>Gets or sets how the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct handles comments when reading through the JSON data.</summary>
         <value>One of the enumeration values that indicates how comments are handled.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[

xml/System.Text.Json/JsonReaderState.xml

@@ -14,10 +14,18 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Defines an opaque type that holds and saves all the relevant state information which must be provided to the <see cref="T:System.Text.Json.Utf8JsonReader" /> to continue reading after processing incomplete data.
-            This type is required to support reentrancy when reading incomplete data, and to continue reading once more data is available. Unlike the <see cref="T:System.Text.Json.Utf8JsonReader" />, which is a ref struct,
-            this type can survive across async/await boundaries, and hence this type is required to provide support for reading more data asynchronously before continuing with a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" />.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Defines an opaque type that holds and saves all the relevant state information, which must be provided to the <see cref="T:System.Text.Json.Utf8JsonReader" /> to continue reading after processing incomplete data.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+`JsonReaderState` is required to support reentrancy when reading incomplete data, and to continue reading once more data is available. 
+Unlike the <xref:System.Text.Json.Utf8JsonReader> struct, which is a ref struct,
+this type can survive across async/await boundaries, and hence it's required to provide support for reading more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonReader>.
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -38,7 +46,7 @@
       <Docs>
         <param name="maxDepth">The maximum depth allowed when reading JSON. This is an optional parameter, and its default value is 64. Reading past this depth throws a <see cref="T:System.Text.Json.JsonReaderException" /></param>
         <param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonReader" /> that is different from the JSON RFC (for example, how to handle comments).
-            This is an optional parameter and, by default, the <see cref="T:System.Text.Json.Utf8JsonReader" /> object follows the JSON RFC strictly (that is, comments within the JSON are invalid).</param>
+            This is an optional parameter and, by default, the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct follows the JSON RFC strictly (that is, comments within the JSON are invalid).</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonReaderState" /> struct.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
@@ -141,7 +149,7 @@ Reading past `MaxDepth` throws a <xref:System.Text.Json.JsonReaderException>.
         <ReturnType>System.SequencePosition</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;. If the <see cref="T:System.Text.Json.Utf8JsonReader" /> object was constructed
+        <summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;. If the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct was constructed
             with a ReadOnlySpan&lt;byte&gt; instead, this will always return a default <see cref="T:System.SequencePosition" />.</summary>
         <value>The current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;.</value>
         <remarks>To be added.</remarks>

xml/System.Text.Json/JsonWriterOptions.xml

@@ -14,11 +14,17 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Allows the user to define custom behavior when writing JSON
-            using the <see cref="T:System.Text.Json.Utf8JsonWriter" />. By default, the JSON is written without
-            any indentation or extra white space. Also, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> will
-            throw an exception if the user attempts to write structurally invalid JSON.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Allows the user to define custom behavior when writing JSON using the <see cref="T:System.Text.Json.Utf8JsonWriter" />.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+By default, the JSON is written without any indentation or extra white space. 
+Also, <xref:System.Text.Json.Utf8JsonWriter> throws an exception if the user attempts to write structurally invalid JSON.
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Indented">
@@ -74,4 +80,4 @@ An example of invalid JSON where the writer will throw (when `SkipValidation` is
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Text.Json/JsonWriterState.xml

@@ -43,7 +43,7 @@ this type can survive across async/await boundaries, and hence this type is requ
         <Parameter Name="options" Type="System.Text.Json.JsonWriterOptions" />
       </Parameters>
       <Docs>
-        <param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object.
+        <param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct.
             By default, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> writes JSON minimized (that is, with no extra white space) and validates that the JSON data being written is structurally valid according to JSON RFC.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonWriterState" /> struct.</summary>
         <remarks>
@@ -53,7 +53,7 @@ this type can survive across async/await boundaries, and hence this type is requ
 
 An instance of this state must be passed to the <xref:System.Text.Json.Utf8JsonWriter> constructor with the output destination.
 Unlike the <xref:System.Text.Json.Utf8JsonWriter>, which is a ref struct, the state can survive across async/await boundaries, and hence this type is required to provide support for reading
-more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonWriter> object.
+more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonWriter> struct.
 
  ]]></format>
         </remarks>
@@ -96,7 +96,7 @@ more data asynchronously before continuing with a new instance of the <xref:Syst
         <ReturnType>System.Int64</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the total number of bytes written by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object so far. This includes data that has been written beyond what has already been committed.</summary>
+        <summary>Gets the total number of bytes written by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct so far. This includes data that has been written beyond what has already been committed.</summary>
         <value>The total number of bytes written.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -117,8 +117,7 @@ more data asynchronously before continuing with a new instance of the <xref:Syst
         <ReturnType>System.Text.Json.JsonWriterOptions</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the custom behavior to use when writing JSON data using the <see cref="T:System.Text.Json.Utf8JsonWriter" /> object, which indicates whether to format the output
-            while writing and whether to skip structural JSON validation or not.</summary>
+        <summary>Gets the custom behavior to use when writing JSON data using the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct.</summary>
         <value>The custom behavior to use when writing JSON data.</value>
         <remarks>To be added.</remarks>
       </Docs>

xml/System.Text.Json/Utf8JsonReader.xml

@@ -19,12 +19,14 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Provides a high-performance API for forward-only, read-only access to the UTF-8 encoded JSON text. It processes the text sequentially with no caching and by default adheres strictly to the <see href="https://tools.ietf.org/html/rfc8259">JSON RFC</see>.</summary>
+    <summary>Provides a high-performance API for forward-only, read-only access to the UTF-8 encoded JSON text.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
 
 ## Remarks
 
+`Utf8JsonReader` processes the text sequentially with no caching and by default adheres strictly to the [JSON RFC](https://tools.ietf.org/html/rfc8259).
+
 When `Utf8JsonReader` encounters invalid JSON, it throws a <xref:System.Text.Json.JsonReaderException>  with basic error information like line number and byte position on the line.
 Since this type is a ref struct, it doesn't directly support async. However, it does provide support for reentrancy to read incomplete data and to continue reading once more data is presented.
 To be able to set max depth while reading OR allow skipping comments, create an instance of <xref:System.Text.Json.JsonReaderState> and pass it to the reader.
@@ -58,7 +60,7 @@ To be able to set max depth while reading OR allow skipping comments, create an
       </Parameters>
       <Docs>
         <param name="jsonData">The UTF-8 encoded JSON text to process.</param>
-        <param name="isFinalBlock"><see langword="true" /> when the input span contains the entire data to process. <see langword="false" /> only if it's known that the input span contains partial data with more data to follow.</param>
+        <param name="isFinalBlock"><see langword="true" /> when the input sequence contains the entire data to process. <see langword="false" /> only if it's known that the input span contains partial data with more data to follow.</param>
         <param name="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" /> and pass that back.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> class.</summary>
         <remarks>
@@ -93,7 +95,7 @@ This is the reason why the constructor accepts a <xref:System.Text.Json.JsonRead
       <Docs>
         <param name="jsonData">The UTF-8 encoded JSON text to process.</param>
         <param name="isFinalBlock"><see langword="true" /> when the input span contains the entire data to process. <see langword="false" /> only if it's known that the input span contains partial data with more data to follow.</param>
-        <param name="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" /> and pass that back.</param>
+        <param name="state">A struct that contains the reader state. On the first call to the constructor, it should reflect a default state; otherwise, it should capture the state from the previous instance instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> and pass that back.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Utf8JsonReader" /> class.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
@@ -543,8 +545,8 @@ For input data within a `ReadOnlySpan<byte>`, this always returns `false`. For i
         <ReturnType>System.SequencePosition</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt; or a default <see cref="T:System.SequencePosition" /> if the <see cref="T:System.Text.Json.Utf8JsonReader" /> object was constructed with a ReadOnlySpan&lt;byte&gt;.</summary>
-        <value>The current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt; or a default <see cref="T:System.SequencePosition" /> if the <see cref="T:System.Text.Json.Utf8JsonReader" /> object was constructed with a ReadOnlySpan&lt;byte&gt;.</value>
+        <summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt; or a default <see cref="T:System.SequencePosition" /> if the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct was constructed with a ReadOnlySpan&lt;byte&gt;.</summary>
+        <value>The current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt; or a default <see cref="T:System.SequencePosition" /> if the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct was constructed with a ReadOnlySpan&lt;byte&gt;.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>