-Fixed missing XML documentation

-Updated custom documentation pages to use MAML
2012-07-22 00:11:57 +12:00
parent 5d83daa804
commit 2d35a5e912
53 changed files with 1874 additions and 3565 deletions
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="PreserveObjectReferences" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!--
+    <summary>
+      <para>Optional summary abstract</para>
+    </summary>
+    -->
+    <introduction>
+      <para>By default Json.NET will serialize all objects it encounters by value.
+      If a list contains two Person references, and both references point to the
+      same object then the JsonSerializer will write out all the names and values
+      for each reference.</para>
+      
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesOff" title="Preserve Object References Off" />
+      
+      <para>In most cases this is the desired result but in certain scenarios
+      writing the second item in the list as a reference to the first is a better
+      solution. If the above JSON was deserialized now then the returned list would
+      contain two completely separate Person objects with the same values. Writing
+      references by value will also cause problems on objects where a circular
+      reference occurs.</para>
+    </introduction>
+    <!-- Add one or more top-level section elements.  These are collapsible.
+         If using <autoOutline />, add an address attribute to identify it
+         and specify a title so that it can be jumped to with a hyperlink. -->
+    <section>
+      <title>PreserveReferencesHandling</title>
+      <content>
+        <para>Settings PreserveReferencesHandling will track object references
+        when serializing and deserializing JSON.</para>
+        
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesOn" title="Preserve Object References On" />       
+        
+        <para>The first Person in the list is serizlied with the addition of an
+        object Id. The second Person in JSON is now only a reference to the first.</para>
+        <para>With PreserveReferencesHandling on now only one Person object is created
+        on deserialization and the list contains two references to it, mirroring
+        what we started with.</para>
+      </content>
+    </section>
+    
+    <section>
+      <title>IsReference</title>
+      <content>
+        <para>The PreserveReferencesHandling setting on the JsonSerializer will
+        change how all objects are serialized and deserialized. For fine grain
+        control over which objects and members should be serialized as a
+        reference there is the IsReference property on the JsonObjectAttribute,
+        JsonArrayAttribute and JsonPropertyAttribute.</para>
+        
+        <para>Setting IsReference on JsonObjectAttribute or JsonArrayAttribute to
+        true will mean the JsonSerializer will always serialize the type the
+        attribute is against as a reference. Setting IsReference on the
+        JsonPropertyAttribute to true will serialize only that property as a
+        reference.</para>
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesAttribute" title="IsReference" />
+      </content>
+    </section>
+    
+    <section>
+      <title>IReferenceResolver</title>
+      <content>
+        <para>To customize how references are generated and resolved the
+        <codeEntityReference>T:Newtonsoft.Json.Serialization.IReferenceResolver</codeEntityReference>
+        interface is available to inherit from and use with
+        the JsonSerializer.</para>
+      </content>
+    </section>
+  </developerConceptualDocument>
+</topic>