Automatic port of System.Text.Json documentation (#4619)

* Automatic port of System.Text.Json documentation * Update JsonSerializerOptions.xml * Update xml/System.Text.Json.Serialization/ReferenceHandler.xml * Apply suggestions from code review Co-authored-by: David Cantu <[email protected]> * Update xml/System.Text.Json.Serialization/ReferenceHandler.xml * fix build warning Co-authored-by: carlossanlop <[email protected]> Co-authored-by: Tom Dykstra <[email protected]> Co-authored-by: David Cantu <[email protected]>
dotnet · BillWagner · Aug 12, 2020 · Aug 11, 2020 · Aug 11, 2020 · Aug 11, 2020
commit 104f6e44a825b37721f5d8e6f9256e18e4803440
diff --git a/xml/System.Text.Json.Serialization/JsonConverter`1.xml b/xml/System.Text.Json.Serialization/JsonConverter`1.xml
@@ -1,4 +1,4 @@
-<Type Name="JsonConverter&lt;T&gt;" FullName="System.Text.Json.Serialization.JsonConverter&lt;T&gt;">
+<Type Name="JsonConverter&lt;T&gt;" FullName="System.Text.Json.Serialization.JsonConverter&lt;T&gt;">
   <TypeSignature Language="C#" Value="public abstract class JsonConverter&lt;T&gt; : System.Text.Json.Serialization.JsonConverter" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit JsonConverter`1&lt;T&gt; extends System.Text.Json.Serialization.JsonConverter" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.Serialization.JsonConverter`1" />
@@ -105,9 +105,17 @@ For more information, see [How to write custom converters for JSON serialization
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <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>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The default value is `true` for converters for value types, and `false` for converters for reference types.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Read">

diff --git a/xml/System.Text.Json.Serialization/ReferenceHandler.xml b/xml/System.Text.Json.Serialization/ReferenceHandler.xml
@@ -1,4 +1,4 @@
-<Type Name="ReferenceHandler" FullName="System.Text.Json.Serialization.ReferenceHandler">
+<Type Name="ReferenceHandler" FullName="System.Text.Json.Serialization.ReferenceHandler">
   <TypeSignature Language="C#" Value="public abstract class ReferenceHandler" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit ReferenceHandler extends System.Object" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.Serialization.ReferenceHandler" />
@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>This class defines how the <see cref="T:System.Text.Json.JsonSerializer" /> deals with references on serialization and deserialization.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -52,8 +52,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns the <see cref="T:System.Text.Json.Serialization.ReferenceResolver" /> used for each serialization call.</summary>
+        <returns>The resolver to use for serialization and deserialization.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -73,9 +73,42 @@
         <ReturnType>System.Text.Json.Serialization.ReferenceHandler</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Metadata properties will be honored when deserializing JSON objects and arrays into reference types and written when serializing reference types. This is necessary to create round-trippable JSON from objects that contain cycles or duplicate references.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+* On Serialize:
+
+  * When writing complex reference types, the serializer also writes metadata properties (`$id`, `$values`, and `$ref`) within them.
+  * The output JSON will contain an extra `$id` property for every object, and for every enumerable type the JSON array emitted will be nested within a JSON object containing an `$id` and `$values` property.
+  * <xref:System.Object.ReferenceEquals(System.Object,System.Object)> is used to determine whether objects are identical.
+  * When an object is identical to a previously serialized one, a pointer (`$ref`) to the identifier (`$id`) of such object is written instead.
+  * No metadata properties are written for value types.
+
+* On Deserialize:
+
+  * The metadata properties within the JSON that are used to preserve duplicated references and cycles will be honored as long as they are well-formed.\*
+  * For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to not using `Preserve`.
+  * For value types, the `$id` metadata property is ignored. A <xref:System.Text.Json.JsonException> is thrown if a `$ref` metadata property is found within the JSON object.
+  * For enumerable value types, the `$values` metadata property is ignored.
+
+\* For the metadata properties within the JSON to be considered well-formed, they must follow these rules:
+
+* The `$id` metadata property must be the first property in the JSON object.
+* A JSON object that contains a `$ref` metadata property must not contain any other properties.
+* The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON.
+* The value of the `$id` and `$ref` metadata properties must be a JSON string.
+* For enumerable types, such as <xref:System.Collections.Generic.List%601>, the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order.
+* For enumerable types, the `$values` metadata property must be a JSON array.
+* The `$values` metadata property is only valid when referring to enumerable types.
+
+If the JSON is not well-formed, a <xref:System.Text.Json.JsonException> is thrown.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Text.Json.Serialization/ReferenceHandler`1.xml b/xml/System.Text.Json.Serialization/ReferenceHandler`1.xml
@@ -1,4 +1,4 @@
-<Type Name="ReferenceHandler&lt;T&gt;" FullName="System.Text.Json.Serialization.ReferenceHandler&lt;T&gt;">
+<Type Name="ReferenceHandler&lt;T&gt;" FullName="System.Text.Json.Serialization.ReferenceHandler&lt;T&gt;">
   <TypeSignature Language="C#" Value="public sealed class ReferenceHandler&lt;T&gt; : System.Text.Json.Serialization.ReferenceHandler where T : ReferenceResolvernew()" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit ReferenceHandler`1&lt;.ctor (class System.Text.Json.Serialization.ReferenceResolver) T&gt; extends System.Text.Json.Serialization.ReferenceHandler" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.Serialization.ReferenceHandler`1" />
@@ -22,8 +22,8 @@
   </Base>
   <Interfaces />
   <Docs>
-    <typeparam name="T">To be added.</typeparam>
-    <summary>To be added.</summary>
+    <typeparam name="T">The type of the <see cref="T:System.Text.Json.Serialization.ReferenceResolver" /> to create on each serialization or deserialization call.</typeparam>
+    <summary>This class defines how the <see cref="T:System.Text.Json.JsonSerializer" /> deals with references on serialization and deserialization.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -61,8 +61,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Creates a new <see cref="T:System.Text.Json.Serialization.ReferenceResolver" /> of type <typeparamref name="T" /> used for each serialization call.</summary>
+        <returns>The new resolver to use for serialization and deserialization.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

diff --git a/xml/System.Text.Json.Serialization/ReferenceResolver.xml b/xml/System.Text.Json.Serialization/ReferenceResolver.xml
@@ -1,4 +1,4 @@
-<Type Name="ReferenceResolver" FullName="System.Text.Json.Serialization.ReferenceResolver">
+<Type Name="ReferenceResolver" FullName="System.Text.Json.Serialization.ReferenceResolver">
   <TypeSignature Language="C#" Value="public abstract class ReferenceResolver" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit ReferenceResolver extends System.Object" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.Serialization.ReferenceResolver" />
@@ -14,7 +14,8 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>This class defines how the <see cref="T:System.Text.Json.JsonSerializer" /> deals with references on serialization and deserialization.
+ Defines the core behavior of preserving references on serialization and deserialization.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -55,9 +56,10 @@
         <Parameter Name="value" Type="System.Object" />
       </Parameters>
       <Docs>
-        <param name="referenceId">To be added.</param>
-        <param name="value">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="referenceId">The identifier of the JSON object or array.</param>
+        <param name="value">The value of the CLR reference type object that results from parsing the JSON object.</param>
+        <summary>Adds an entry to the bag of references using the specified id and value.
+ This method gets called when an $id metadata property from a JSON object is read.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -81,10 +83,11 @@
         <Parameter Name="alreadyExists" Type="System.Boolean" RefType="out" />
       </Parameters>
       <Docs>
-        <param name="value">To be added.</param>
-        <param name="alreadyExists">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="value">The value of the CLR reference type object to get an id for.</param>
+        <param name="alreadyExists">When this method returns, <see langword="true" /> if a reference to value already exists; otherwise, <see langword="false" />.</param>
+        <summary>Gets the reference identifier of the specified value if exists; otherwise a new id is assigned.
+ This method gets called before a CLR object is written so we can decide whether to write $id and enumerate the rest of its properties or $ref and step into the next object.</summary>
+        <returns>The reference id for the specified object.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -107,9 +110,10 @@
         <Parameter Name="referenceId" Type="System.String" />
       </Parameters>
       <Docs>
-        <param name="referenceId">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="referenceId">The reference id related to the returned object.</param>
+        <summary>Returns the CLR reference type object related to the specified reference id.
+ This method gets called when $ref metadata property is read.</summary>
+        <returns>The reference type object related to the specified reference id.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

diff --git a/xml/System.Text.Json/JsonSerializerDefaults.xml b/xml/System.Text.Json/JsonSerializerDefaults.xml
@@ -1,4 +1,4 @@
-<Type Name="JsonSerializerDefaults" FullName="System.Text.Json.JsonSerializerDefaults">
+<Type Name="JsonSerializerDefaults" FullName="System.Text.Json.JsonSerializerDefaults">
   <TypeSignature Language="C#" Value="public enum JsonSerializerDefaults" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed JsonSerializerDefaults extends System.Enum" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.JsonSerializerDefaults" />
@@ -13,7 +13,7 @@
     <BaseTypeName>System.Enum</BaseTypeName>
   </Base>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Specifies what default options are used by <see cref="T:System.Text.Json.JsonSerializerOptions" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -34,7 +34,16 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Specifies that general-purpose values should be used. These are the same settings applied if a <see cref="T:System.Text.Json.JsonSerializerDefaults" /> isn't specified.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This option implies that property names are treated as case-sensitive and that "PascalCase" name formatting should be employed.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Web">
@@ -54,7 +63,16 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Specifies that values should be used more appropriate to web-based scenarios.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This option implies that property names are treated as case-insensitive and that "camelCase" name formatting should be employed.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml
@@ -1,4 +1,4 @@
-<Type Name="JsonSerializerOptions" FullName="System.Text.Json.JsonSerializerOptions">
+<Type Name="JsonSerializerOptions" FullName="System.Text.Json.JsonSerializerOptions">
   <TypeSignature Language="C#" Value="public sealed class JsonSerializerOptions" />
   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit JsonSerializerOptions extends System.Object" />
   <TypeSignature Language="DocId" Value="T:System.Text.Json.JsonSerializerOptions" />
@@ -63,8 +63,8 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa
         <Parameter Name="defaults" Type="System.Text.Json.JsonSerializerDefaults" Index="0" FrameworkAlternate="net-5.0" />
       </Parameters>
       <Docs>
-        <param name="defaults">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="defaults">The <see cref="T:System.Text.Json.JsonSerializerDefaults" /> to reason about.</param>
+        <summary>Constructs a new <see cref="T:System.Text.Json.JsonSerializerOptions" /> instance with a predefined set of options determined by the specified <see cref="T:System.Text.Json.JsonSerializerDefaults" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -214,7 +214,8 @@ We recommend that you leave this value unchanged unless changing it makes an obs
         <ReturnType>System.Text.Json.Serialization.JsonIgnoreCondition</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Specifies a condition to determine when properties with default values are ignored during serialization or deserialization.
+ The default value is <see cref="F:System.Text.Json.Serialization.JsonIgnoreCondition.Never" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -551,7 +552,27 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa
       <Docs>
         <summary>Configures how object references are handled when reading and writing JSON.</summary>
         <value>To be added.</value>
-        <remarks>This option provides a convenient way to deal with circularity in object graphs.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+By default, serialization does not support objects with cycles and does not preserve duplicate references. Metadata properties will not be written when serializing reference types and will be treated as regular properties on deserialize.
+
+* On Serialize:
+
+  * Treats duplicate object references as if they were unique and writes all their properties.
+  * The serializer throws a <xref:System.Text.Json.JsonException> if an object contains a cycle.
+
+* On Deserialize:
+
+  * Metadata properties (`$id`, `$values`, and `$ref`) will not be consumed and therefore will be treated as regular JSON properties.
+  * The metadata properties can map to a real property on the returned object if the property names match, or will be added to the <xref:System.Text.Json.Serialization.JsonExtensionDataAttribute> overflow dictionary, if one exists; otherwise, they are ignored.
+
+Use <xref:System.Text.Json.Serialization.ReferenceHandler.Preserve> to enable unique object reference preservation on serialization and metadata consumption to read preserved references on deserialization.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteIndented">