Link to System.Text.Json conceptual docs (#3502)

tdykstra · mairaw · web-flow · commit c8ee7ad054ce · 2019-11-20T14:34:37.000-08:00
* link to conceptual docs

* typos

* move links to remarks

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* Update xml/System.Text.Json.Serialization/JsonConverterAttribute.xml

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* Update xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel &lt;mairaw@microsoft.com&gt;
diff --git a/xml/System.Text.Json.Serialization/JsonConverter.xml b/xml/System.Text.Json.Serialization/JsonConverter.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Converts an object or value to or from JSON.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="CanConvert">
diff --git a/xml/System.Text.Json.Serialization/JsonConverterAttribute.xml b/xml/System.Text.Json.Serialization/JsonConverterAttribute.xml
@@ -30,7 +30,9 @@ The specified converter type must derive from <xref:System.Text.Json.Serializati
 When placed on a property, the specified converter will always be used.
 
 When placed on a type, the specified converter will be used unless a compatible converter is added to the <xref:System.Text.Json.JsonSerializerOptions.Converters?displayProperty=nameWithType> collection or there is another <xref:System.Text.Json.Serialization.JsonConverterAttribute> on a property of the same type.
-            
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#register-a-custom-converter). 
+        
           ]]></format>
     </remarks>
   </Docs>
diff --git a/xml/System.Text.Json.Serialization/JsonConverterFactory.xml b/xml/System.Text.Json.Serialization/JsonConverterFactory.xml
@@ -22,6 +22,8 @@
 
 This is useful for converters supporting generics, such as a converter for <xref:System.Collections.Generic.List`1>.
 
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#register-a-custom-converter).
+
           ]]></format>
     </remarks>
   </Docs>
@@ -67,7 +69,15 @@ This is useful for converters supporting generics, such as a converter for <xref
         <param name="options">The serialization options to use.</param>
         <summary>Creates a converter for a specified type.</summary>
         <returns>A converter for which <typeparamref name="T" /> is compatible with <paramref name="typeToConvert" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#sample-factory-pattern-converter).
+
+ ]]></format>
+    </remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Text.Json.Serialization/JsonConverter`1.xml b/xml/System.Text.Json.Serialization/JsonConverter`1.xml
@@ -19,7 +19,15 @@
   <Docs>
     <typeparam name="T">The type of object or value handled by the converter.</typeparam>
     <summary>Converts an object or value to or from JSON.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -69,6 +77,8 @@
 
 The default implementation is to return `true` when `typeToConvert` equals `typeof(T)`.
 
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#steps-to-follow-the-basic-pattern).
+
           ]]></format>
         </remarks>
       </Docs>
@@ -99,7 +109,15 @@ The default implementation is to return `true` when `typeToConvert` equals `type
         <param name="options">An object that specifies serialization options to use.</param>
         <summary>Reads and converts the JSON to type <typeparamref name="T" />.</summary>
         <returns>The converted value.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#steps-to-follow-the-basic-pattern).
+
+ ]]></format>
+    </remarks>
       </Docs>
     </Member>
     <Member MemberName="Write">
@@ -134,6 +152,8 @@ The default implementation is to return `true` when `typeToConvert` equals `type
 
 A converter may throw any exception, but it should throw <xref:System.Text.Json.JsonException> when the JSON cannot be created.
 
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#steps-to-follow-the-basic-pattern).
+
           ]]></format>
         </remarks>
       </Docs>
diff --git a/xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml b/xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml
@@ -33,6 +33,8 @@ During serialization, the name of the extension data property is not included in
             
 If there is more than one property on a type with this extension data attribute, or if the property itself is not of the correct <see cref="T:System.Collections.Generic.IDictionary`2" /> type, an <xref:System.InvalidOperationException> is thrown during the first serialization or deserialization of that type.
 
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#handle-overflow-json).
+
             ]]></format>
     </remarks>
   </Docs>
diff --git a/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml b/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml
@@ -20,7 +20,15 @@
   </Attributes>
   <Docs>
     <summary>Prevents a property from being serialized or deserialized.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#exclude-individual-properties).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization/JsonPropertyNameAttribute.xml b/xml/System.Text.Json.Serialization/JsonPropertyNameAttribute.xml
@@ -20,7 +20,15 @@
   </Attributes>
   <Docs>
     <summary>Specifies the property name that is present in the JSON when serializing and deserializing. This overrides any naming policy specified by <see cref="T:System.Text.Json.JsonNamingPolicy" />.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#customize-individual-property-names).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization/JsonStringEnumConverter.xml b/xml/System.Text.Json.Serialization/JsonStringEnumConverter.xml
@@ -22,6 +22,8 @@
 
 Reading is case insensitive. Writing can be customized by using a <xref:System.Text.Json.JsonNamingPolicy>.
 
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#enums-as-strings).
+
           ]]></format>
     </remarks>
   </Docs>
diff --git a/xml/System.Text.Json/JsonCommentHandling.xml b/xml/System.Text.Json/JsonCommentHandling.xml
@@ -14,7 +14,15 @@
   </Base>
   <Docs>
     <summary>Defines how the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct handles comments.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#allow-comments-and-trailing-commas).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Allow">
diff --git a/xml/System.Text.Json/JsonDocument.xml b/xml/System.Text.Json/JsonDocument.xml
@@ -23,6 +23,9 @@
       <format><![CDATA[
       
 This class utilizes resources from pooled memory to minimize the impact of the garbage collector (GC) in high-usage scenarios. Failure to properly dispose this object will result in the memory not being returned to the pool, which will increase GC impact across various parts of the framework.
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#utf8jsonreader-utf8jsonwriter-and-jsondocument).
+
               
       ]]></format>
     </remarks>
diff --git a/xml/System.Text.Json/JsonDocumentOptions.xml b/xml/System.Text.Json/JsonDocumentOptions.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Provides the ability for the user to define custom behavior when parsing JSON to create a <see cref="T:System.Text.Json.JsonDocument" />.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="AllowTrailingCommas">
diff --git a/xml/System.Text.Json/JsonElement.xml b/xml/System.Text.Json/JsonElement.xml
@@ -20,7 +20,15 @@
   </Attributes>
   <Docs>
     <summary>Represents a specific JSON value within a <see cref="T:System.Text.Json.JsonDocument" />.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-jsondocument-for-access-to-data).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Clone">
@@ -72,7 +80,15 @@ If this <xref:System.Text.Json.JsonElement> is itself the output of a previous c
       <Docs>
         <summary>Gets an enumerator to enumerate the values in the JSON array represented by this JsonElement.</summary>
         <returns>An enumerator to enumerate the values in the JSON array represented by this JsonElement.</returns>
-        <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-jsondocument-for-access-to-data).
+
+ ]]></format>
+    </remarks>
         <exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Array" />.</exception>
         <exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
       </Docs>
@@ -120,7 +136,15 @@ If this <xref:System.Text.Json.JsonElement> is itself the output of a previous c
       <Docs>
         <summary>Gets the number of values contained within the current array value.</summary>
         <returns>The number of values contained within the current array value.</returns>
-        <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-jsondocument-for-access-to-data).
+
+ ]]></format>
+    </remarks>
         <exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Array" />.</exception>
         <exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
       </Docs>
@@ -502,6 +526,8 @@ Property name matching is performed as an ordinal, case-sensitive comparison.
 
 If a property is defined multiple times for the same object, the method matches the last such definition.
 
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-jsondocument-for-access-to-data).
+
           ]]></format>
         </remarks>
         <exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Object" />.</exception>
@@ -1285,6 +1311,8 @@ Property name matching is performed as an ordinal, case-sensitive comparison.
 
 If a property is defined multiple times for the same object, the method matches the last such definition.
 
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-jsondocument-for-access-to-data).
+
           ]]></format>
         </remarks>
         <exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.Object" />.</exception>
diff --git a/xml/System.Text.Json/JsonException.xml b/xml/System.Text.Json/JsonException.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Defines a custom exception object that is thrown when invalid JSON text is encountered, when the defined maximum depth is passed, or the JSON text is not compatible with the type of a property on an object.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to write custom converters for JSON serialization](~/docs/standard/serialization/system-text-json-converters-how-to.md#error-handling).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json/JsonNamingPolicy.xml b/xml/System.Text.Json/JsonNamingPolicy.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Determines the naming policy used to convert a string-based name to another format, such as a camel-casing format.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#customize-json-names-and-values).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -53,7 +61,15 @@
       <Docs>
         <summary>Gets the naming policy for camel-casing.</summary>
         <value>The naming policy for camel-casing.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-camel-case-for-all-json-property-names).
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ConvertName">
@@ -78,7 +94,15 @@
         <param name="name">The name to convert.</param>
         <summary>When overridden in a derived class, converts the specified name according to the policy.</summary>
         <returns>The converted name.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-a-custom-json-property-naming-policy).
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Text.Json/JsonReaderOptions.xml b/xml/System.Text.Json/JsonReaderOptions.xml
@@ -15,7 +15,15 @@
   <Interfaces />
   <Docs>
     <summary>Provides the ability for the user to define custom behavior when reading JSON.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information, see [How to serialize and deserialize JSON](~/docs/standard/serialization/system-text-json-how-to.md#use-utf8jsonreader).
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="AllowTrailingCommas">
@@ -41,7 +49,7 @@
       <Docs>
         <summary>Gets or sets a value that defines whether an extra comma at the end of a list of JSON values in an object or array is allowed (and ignored) within the JSON payload being read. </summary>
         <value>
-          <see langword="true" /> if an exra comma is allowed; otherwise, <see langword="false" />.</value>
+          <see langword="true" /> if an extra comma is allowed; otherwise, <see langword="false" />.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
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/JsonTokenType.xml b/xml/System.Text.Json/JsonTokenType.xml
diff --git a/xml/System.Text.Json/JsonValueKind.xml b/xml/System.Text.Json/JsonValueKind.xml
diff --git a/xml/System.Text.Json/JsonWriterOptions.xml b/xml/System.Text.Json/JsonWriterOptions.xml
diff --git a/xml/System.Text.Json/Utf8JsonReader.xml b/xml/System.Text.Json/Utf8JsonReader.xml
diff --git a/xml/System.Text.Json/Utf8JsonWriter.xml b/xml/System.Text.Json/Utf8JsonWriter.xml
