various improvements to STJ docs (#7517)

gewarren · web-flow · commit 94a36141ebbe · 2021-12-22T16:49:29.000-08:00
diff --git a/xml/System.Text.Json.Nodes/JsonArray.xml b/xml/System.Text.Json.Nodes/JsonArray.xml
@@ -39,8 +39,7 @@
 
 ## Remarks
 
-It is safe to perform multiple concurrent read operations on a <xref:System.Text.Json.Nodes.JsonArray>,
-            but issues can occur if the collection is modified while it's being read.
+It is safe to perform multiple concurrent read operations on a <xref:System.Text.Json.Nodes.JsonArray>, but issues can occur if the collection is modified while it's being read.
 
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json.Nodes/JsonNode.xml b/xml/System.Text.Json.Nodes/JsonNode.xml
@@ -138,12 +138,11 @@
 
 ## Remarks
 
-{T} can be the type or base type of the underlying value.
-              If the underlying value is a <xref:System.Text.Json.JsonElement> then {T} can also be the type of any primitive
-              value supported by current <xref:System.Text.Json.JsonElement>.
-              Specifying the <xref:System.Object> type for {T} will always succeed and return the underlying value as <xref:System.Object>.<br />
-              The underlying value of a <xref:System.Text.Json.Nodes.JsonValue> after deserialization is an instance of <xref:System.Text.Json.JsonElement>,
-              otherwise it's the value specified when the <xref:System.Text.Json.Nodes.JsonValue> was created.
+{T} can be the type or base type of the underlying value. If the underlying value is a <xref:System.Text.Json.JsonElement> then {T} can also be the type of any primitive value supported by current <xref:System.Text.Json.JsonElement>.
+
+Specifying the <xref:System.Object> type for {T} will always succeed and return the underlying value as <xref:System.Object>.
+
+The underlying value of a <xref:System.Text.Json.Nodes.JsonValue> after deserialization is an instance of <xref:System.Text.Json.JsonElement>,otherwise it's the value specified when the <xref:System.Text.Json.Nodes.JsonValue> was created.
 
           ]]></format>
         </remarks>
@@ -1970,7 +1969,7 @@
         <ReturnType>System.Nullable&lt;System.Text.Json.Nodes.JsonNodeOptions&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Options to control the behavior.</summary>
+        <summary>Gets the options to control the behavior.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -2061,7 +2060,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
         <param name="utf8Json">JSON text to parse.</param>
         <param name="nodeOptions">Options to control the node behavior after parsing.</param>
         <param name="documentOptions">Options to control the document behavior during parsing.</param>
-        <summary>Parse a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a <see cref="T:System.Text.Json.Nodes.JsonNode" />.  The Stream will be read to completion.</summary>
+        <summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a <see cref="T:System.Text.Json.Nodes.JsonNode" />.  The Stream will be read to completion.</summary>
         <returns>A <see cref="T:System.Text.Json.Nodes.JsonNode" /> representation of the JSON value.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.Text.Json.JsonException">
@@ -2219,7 +2218,7 @@ This method makes a copy of the data the reader acted on, so there is no caller
       <Docs>
         <param name="writer">The <see cref="T:System.Text.Json.Utf8JsonWriter" />.</param>
         <param name="options">Options to control the serialization behavior.</param>
-        <summary>Write the <see cref="T:System.Text.Json.Nodes.JsonNode" /> into the provided <see cref="T:System.Text.Json.Utf8JsonWriter" /> as JSON.</summary>
+        <summary>Writes the <see cref="T:System.Text.Json.Nodes.JsonNode" /> into the provided <see cref="T:System.Text.Json.Utf8JsonWriter" /> as JSON.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="writer" /> parameter is <see langword="null" />.</exception>
       </Docs>
diff --git a/xml/System.Text.Json.Nodes/JsonNodeOptions.xml b/xml/System.Text.Json.Nodes/JsonNodeOptions.xml
@@ -40,8 +40,9 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Specifies whether property names on <see cref="T:System.Text.Json.Nodes.JsonObject" /> are case insensitive.</summary>
-        <value>To be added.</value>
+        <summary>Gets or sets a value that indicates whether property names on <see cref="T:System.Text.Json.Nodes.JsonObject" /> are case insensitive.</summary>
+        <value>
+          <see langword="true" /> if property names are case insensitive; <see langword="false" /> if property names are case sensitive.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Text.Json.Nodes/JsonObject.xml b/xml/System.Text.Json.Nodes/JsonObject.xml
@@ -42,8 +42,7 @@
 
 ## Remarks
 
-It's safe to perform multiple concurrent read operations on a <xref:System.Text.Json.Nodes.JsonObject>,
-            but issues can occur if the collection is modified while it's being read.
+It's safe to perform multiple concurrent read operations on a <xref:System.Text.Json.Nodes.JsonObject>, but issues can occur if the collection is modified while it's being read.
 
       ]]></format>
     </remarks>
@@ -589,7 +588,7 @@ This member is an explicit interface member implementation. It can be used only
       <Docs>
         <param name="writer">The <see cref="T:System.Text.Json.Utf8JsonWriter" />.</param>
         <param name="options">Options to control the serialization behavior.</param>
-        <summary>Write the <see cref="T:System.Text.Json.Nodes.JsonNode" /> into the provided <see cref="T:System.Text.Json.Utf8JsonWriter" /> as JSON.</summary>
+        <summary>Writes the <see cref="T:System.Text.Json.Nodes.JsonNode" /> into the provided <see cref="T:System.Text.Json.Utf8JsonWriter" /> as JSON.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="writer" /> parameter is <see langword="null" />.</exception>
       </Docs>
diff --git a/xml/System.Text.Json.Nodes/JsonValue.xml b/xml/System.Text.Json.Nodes/JsonValue.xml
@@ -1083,12 +1083,11 @@
 
 ## Remarks
 
-{T} can be the type or base type of the underlying value.
-              If the underlying value is a <xref:System.Text.Json.JsonElement> then {T} can also be the type of any primitive
-              value supported by current <xref:System.Text.Json.JsonElement>.
-              Specifying the <xref:System.Object> type for {T} will always succeed and return the underlying value as <xref:System.Object>.<br />
-              The underlying value of a <xref:System.Text.Json.Nodes.JsonValue> after deserialization is an instance of <xref:System.Text.Json.JsonElement>,
-              otherwise it's the value specified when the <xref:System.Text.Json.Nodes.JsonValue> was created.
+{T} can be the type or base type of the underlying value. If the underlying value is a <xref:System.Text.Json.JsonElement>, then {T} can also be the type of any primitive value supported by current <xref:System.Text.Json.JsonElement>.
+
+Specifying the <xref:System.Object> type for {T} will always succeed and return the underlying value as <xref:System.Object>.
+
+The underlying value of a <xref:System.Text.Json.Nodes.JsonValue> after deserialization is an instance of <xref:System.Text.Json.JsonElement>, otherwise it's the value specified when the <xref:System.Text.Json.Nodes.JsonValue> was created.
 
           ]]></format>
         </remarks>
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
@@ -19,7 +19,7 @@
   <Docs>
     <typeparam name="TCollection">The collection type.</typeparam>
     <summary>Provides serialization metadata about a collection type.</summary>
-    <remarks>This API is for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
+    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
@@ -24,7 +24,7 @@
 
 ## Remarks
 
-This API is for use by the output of the System.Text.Json source generator and should not be called directly.
+This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
 
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
@@ -20,7 +20,7 @@
 
 ## Remarks
 
-This API is for use by the output of the System.Text.Json source generator and should not be called directly.
+This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
 
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Provides JSON serialization-related metadata about a property or field.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members />
 </Type>
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml
@@ -20,7 +20,7 @@
 
 ## Remarks
 
-This API is for use by the output of the System.Text.Json source generator and should not be called directly.
+This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
 
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json.Serialization/IJsonOnDeserialized.xml b/xml/System.Text.Json.Serialization/IJsonOnDeserialized.xml
@@ -17,8 +17,7 @@
 
 ## Remarks
 
-This behavior is only supported on types representing JSON objects.
-            Types that have a custom converter or represent either collections or primitive values do not support this behavior.
+This behavior is only supported on types representing JSON objects. Types that have a custom converter or represent either collections or primitive values do not support this behavior.
 
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json.Serialization/JsonConverterFactory.xml b/xml/System.Text.Json.Serialization/JsonConverterFactory.xml
@@ -47,7 +47,7 @@ For more information, see [How to write custom converters for JSON serialization
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>When overidden in a derived class, initializes a new instance of the <see cref="T:System.Text.Json.Serialization.JsonConverterFactory" /> class.</summary>
+        <summary>When overridden in a derived class, initializes a new instance of the <see cref="T:System.Text.Json.Serialization.JsonConverterFactory" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Text.Json.Serialization/JsonConverter`1.xml b/xml/System.Text.Json.Serialization/JsonConverter`1.xml
@@ -109,7 +109,7 @@ For more information, see [How to write custom converters for JSON serialization
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Indicates whether <see langword="null" /> should be passed to the converter on serialization, and whether <see cref="F:System.Text.Json.JsonTokenType.Null" /> should be passed on deserialization.</summary>
+        <summary>Gets a value that indicates whether <see langword="null" /> should be passed to the converter on serialization, and whether <see cref="F:System.Text.Json.JsonTokenType.Null" /> should be passed on deserialization.</summary>
         <value>To be added.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
diff --git a/xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml b/xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml
@@ -63,7 +63,7 @@ For more information, see [How to handle overflow JSON with System.Text.Json](/d
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>Instantiates a new instance of the <see cref="T:System.Text.Json.Serialization.JsonExtensionDataAttribute" /> class.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Text.Json.Serialization.JsonExtensionDataAttribute" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml b/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml
@@ -76,7 +76,7 @@ For more information, see [How to ignore properties with System.Text.Json](/dotn
         <ReturnType>System.Text.Json.Serialization.JsonIgnoreCondition</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Specifies the condition that must be met before a property will be ignored.</summary>
+        <summary>Gets or sets the condition that must be met before a property will be ignored.</summary>
         <value>To be added.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
diff --git a/xml/System.Text.Json.Serialization/JsonPropertyOrderAttribute.xml b/xml/System.Text.Json.Serialization/JsonPropertyOrderAttribute.xml
@@ -71,7 +71,7 @@ If multiple properties have the same value, the ordering is undefined between th
       </ReturnValue>
       <Docs>
         <summary>Gets the serialization order of the property.</summary>
-        <value>To be added.</value>
+        <value>The serialization order of the property.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
diff --git a/xml/System.Text.Json.Serialization/JsonSerializableAttribute.xml b/xml/System.Text.Json.Serialization/JsonSerializableAttribute.xml
@@ -61,7 +61,7 @@
         <ReturnType>System.Text.Json.Serialization.JsonSourceGenerationMode</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Determines what the source generator should generate for the type. If the value is <see cref="F:System.Text.Json.Serialization.JsonSourceGenerationMode.Default" />, then the setting specified on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode" /> will be used.</summary>
+        <summary>Gets or sets the mode that indicates what the source generator should generate for the type. If the value is <see cref="F:System.Text.Json.Serialization.JsonSourceGenerationMode.Default" />, then the setting specified on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode" /> will be used.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -82,14 +82,14 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The name of the property for the generated <see cref="T:System.Text.Json.Serialization.Metadata.JsonTypeInfo`1" /> for the type on the generated, derived <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" /> type.</summary>
+        <summary>Gets or sets the name of the property for the generated <see cref="T:System.Text.Json.Serialization.Metadata.JsonTypeInfo`1" /> for the type on the generated, derived <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" /> type.</summary>
         <value>To be added.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-Useful to resolve a name collision with another type in the compilation closure.
+This property is useful for resolving a name collision with another type in the compilation closure.
 
           ]]></format>
         </remarks>
diff --git a/xml/System.Text.Json.Serialization/JsonSerializerContext.xml b/xml/System.Text.Json.Serialization/JsonSerializerContext.xml
@@ -41,8 +41,7 @@
 
 ## Remarks
 
-If no instance options are passed, then no options are set until the context is bound using <xref:System.Text.Json.JsonSerializerOptions.AddContext``1>,
-            or until <xref:System.Text.Json.Serialization.JsonSerializerContext.Options> is called, where a new options instance is created and bound.
+If no instance options are passed, then no options are set until the context is bound using <xref:System.Text.Json.JsonSerializerOptions.AddContext``1> or until <xref:System.Text.Json.Serialization.JsonSerializerContext.Options> is called, where a new options instance is created and bound.
 
           ]]></format>
         </remarks>
@@ -88,8 +87,8 @@ If no instance options are passed, then no options are set until the context is
         <Parameter Name="type" Type="System.Type" />
       </Parameters>
       <Docs>
-        <param name="type">The type to fetch metadata about.</param>
-        <summary>Returns a <see cref="T:System.Text.Json.Serialization.Metadata.JsonTypeInfo" /> instance representing the given type.</summary>
+        <param name="type">The type to fetch metadata for.</param>
+        <summary>Gets metadata for the specified type.</summary>
         <returns>The metadata for the specified type, or <see langword="null" /> if the context has no metadata for the type.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -110,7 +109,7 @@ If no instance options are passed, then no options are set until the context is
         <ReturnType>System.Text.Json.JsonSerializerOptions</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the run-time specified options of the context. If no options were passed when instanciating the context, then a new instance is bound and returned.</summary>
+        <summary>Gets the run-time specified options of the context. If no options were passed when instantiating the context, then a new instance is bound and returned.</summary>
         <value>To be added.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
diff --git a/xml/System.Text.Json.Serialization/JsonSourceGenerationOptionsAttribute.xml b/xml/System.Text.Json.Serialization/JsonSourceGenerationOptionsAttribute.xml
@@ -37,7 +37,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>Instructs the System.Text.Json source generator to assume the specified options will be used at run time via <see cref="T:System.Text.Json.JsonSerializerOptions" />.</summary>
+        <summary>Initializes a new instance of <see cref="T:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -183,7 +183,7 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets a value that indicates whether JSON output should be pretty-printed.</summary>
+        <summary>Gets or sets a value that indicates whether JSON output is pretty-printed.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Text.Json.Serialization/ReferenceHandler.xml b/xml/System.Text.Json.Serialization/ReferenceHandler.xml
diff --git a/xml/System.Text.Json.Serialization/ReferenceHandler`1.xml b/xml/System.Text.Json.Serialization/ReferenceHandler`1.xml
diff --git a/xml/System.Text.Json.Serialization/ReferenceResolver.xml b/xml/System.Text.Json.Serialization/ReferenceResolver.xml
diff --git a/xml/System.Text.Json/JsonDocument.xml b/xml/System.Text.Json/JsonDocument.xml
diff --git a/xml/System.Text.Json/JsonException.xml b/xml/System.Text.Json/JsonException.xml
diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml
diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml
diff --git a/xml/System.Text.Json/JsonWriterOptions.xml b/xml/System.Text.Json/JsonWriterOptions.xml
diff --git a/xml/System.Text.Json/Utf8JsonWriter.xml b/xml/System.Text.Json/Utf8JsonWriter.xml
