-Fixed bugs and made improvements to help

gx-chan · Jul 22, 2012 · 2097219 · 2097219
1 parent e156978
commit 2097219
Show file tree

Hide file tree

Showing 22 changed files with 358 additions and 122 deletions.
diff --git a/Doc/ContractResolver.aml b/Doc/ContractResolver.aml
@@ -7,7 +7,8 @@
     </summary>
     -->
     <introduction>
-      <para>The IContractResolver interface provides a way to customize how the
+      <para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
+      interface provides a way to customize how the
       JsonSerializer serializes and deserializes .NET objects to JSON.</para>
       <para>Implementing the IContractResolver interface and then assigning an
       instance to a JsonSerializer lets you control whether the object is
@@ -44,5 +45,10 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ContractResolver" title="ContractResolver" />
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/ConvertingJSONandXML.aml b/Doc/ConvertingJSONandXML.aml
@@ -24,6 +24,12 @@
   <listItem><para>Empty elements are null.</para></listItem>
 </list>
 
+<alert class="note">
+  <para>The version of Json.NET being used in your application will change what XML conversion methods are available.
+  SerializeXmlNode/DeserializeXmlNode are available when the framework supports XmlDocument,
+  SerializeXNode/DeserializeXNode are available when the framework supports XDocument.</para>
+</alert>
+
       </content>
     </section>
     <section>
@@ -36,7 +42,16 @@
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="SerializeXmlNode" title="Converting XML to JSON with SerializeXmlNode" />
 
-      </content>
+       <para>Because multiple nodes with a the same name at the same level are grouped together into an array
+       the convernsion process can produce different JSON depending on the number of nodes. For example if some
+       XML for a user has a single <codeInline>&lt;Role&gt;</codeInline> node then that role will be text against
+       a JSON <codeInline>"Role"</codeInline> property, but if the user has multiple <codeInline>&lt;Role&gt;</codeInline>
+       nodes then the role values will be placed in a JSON array.</para>
+
+       <para>To fix this situation a custom XML attribute can be added to force a JSON array to be created.</para>
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="ForceJsonArray" title="Attribute to Force a JSON Array" />
+    </content>
     </section>
     <section>
       <title>DeserializeXmlNode</title>
@@ -55,5 +70,9 @@
 
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.Converters.XmlNodeConverter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonConvert</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/CustomCreationConverter.aml b/Doc/CustomCreationConverter.aml
@@ -7,14 +7,12 @@
     </summary>
     -->
     <introduction>
-      <para>The CustomCreationConverter is a JsonConverter that provides a way
+      <para>The <codeEntityReference>T:Newtonsoft.Json.Converters.CustomCreationConverter`1</codeEntityReference>
+      is a JsonConverter that provides a way
       to customize how an object is created during JSON deserialization. Once
       the object has been created it will then have values populated onto it by
       the serializer.</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>Example</title>
       <content>
@@ -25,5 +23,8 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="CustomCreationConverterExample" title="CustomCreationConverter Example" />
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.Converters.CustomCreationConverter`1</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/DatesInJSON.aml b/Doc/DatesInJSON.aml
@@ -28,9 +28,9 @@
 <linkText>ISO 8601 standard</linkText>
 <linkUri>http://en.wikipedia.org/wiki/ISO_8601</linkUri>
 <linkTarget>_blank</linkTarget>
-</externalLink>: 2012-03-19T07:22Z.</para>
+</externalLink>: <codeInline>"2012-03-19T07:22Z"</codeInline>.</para>
         <para>Prior to Json.NET 4.5 dates were written using the Microsoft
-        format: "\/Date(1198908717056)\/". If you want to use this format, or
+        format: <codeInline>"\/Date(1198908717056)\/"</codeInline>. If you want to use this format, or
         you want to maintain compatibility with Microsoft JSON serializers or
         older versions of Json.NET then change the
         <codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference>
@@ -76,7 +76,7 @@
       <title>IsoDateTimeConverter</title>
       <content>
       <alert class="note">
-  <para>Since Json.NET 4.5 dates are written using the ISO 8601
+  <para>From Json.NET 4.5 and onwards dates are written using the ISO 8601
         format by default and using this converter is unnecessary.</para>
 </alert>
         <para>IsoDateTimeConverter seralizes a DateTime to an <externalLink>
@@ -89,5 +89,11 @@
         further customize the formatted string.</para>
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.DateTimeZoneHandling</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Converters.JavaScriptDateTimeConverter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Converters.IsoDateTimeConverter</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/Introduction.aml b/Doc/Introduction.aml
@@ -43,6 +43,25 @@ and write from your objects.</para>
 </content>
 </section>
 
+<section>
+ <title>Getting Started</title>
+ <content>
+
+<list class="bullet">
+  <listItem><para><externalLink>
+<linkText>Serializing and Deserializing JSON</linkText>
+<linkUri>SerializingJSON.htm</linkUri>
+<linkTarget>_self</linkTarget>
+</externalLink></para></listItem>
+  <listItem><para><externalLink>
+<linkText>LINQ to JSON</linkText>
+<linkUri>LINQtoJSON.htm</linkUri>
+<linkTarget>_self</linkTarget>
+</externalLink></para></listItem>
+</list>
+
+ </content>
+</section>
 <section>
  <title>History</title>
  <content><para>Json.NET grew out of projects I was working on in late 2005 involving JavaScript,
@@ -87,6 +106,18 @@ and write from your objects.</para>
             </a>
  </p>
  </markup>
+    <relatedTopics>
+      <externalLink>
+        <linkText>Serializing and Deserializing JSON</linkText>
+        <linkUri>SerializingJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <externalLink>
+        <linkText>LINQ to JSON</linkText>
+        <linkUri>LINQtoJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+    </relatedTopics>
 
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/LINQtoJSON.aml b/Doc/LINQtoJSON.aml
@@ -46,8 +46,7 @@
         objects are
         <codeEntityReference>M:Newtonsoft.Json.Linq.JToken.Children</codeEntityReference>
         and
-        <codeEntityReference>P:Newtonsoft.Json.Linq.JToken.Item(System.Object)</codeEntityReference>
-        .</para>
+        <codeEntityReference>P:Newtonsoft.Json.Linq.JToken.Item(System.Object)</codeEntityReference>.</para>
 
         <para>Children returns all the children of that object. If it is a
         JObject it will return a collection of properties to work with and if
@@ -68,5 +67,16 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonDeserializeExample" title="Deserializing Using LINQ Example" />
       </content>
     </section>
+    <relatedTopics>
+      <externalLink>
+        <linkText>Querying LINQ to JSON with SelectToken</linkText>
+        <linkUri>SelectToken.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+
+      <codeEntityReference>T:Newtonsoft.Json.Linq.JObject</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Linq.JArray</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Linq.JValue</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/PreserveObjectReferences.aml b/Doc/PreserveObjectReferences.aml
@@ -27,7 +27,7 @@
     <section>
       <title>PreserveReferencesHandling</title>
       <content>
-        <para>Settings PreserveReferencesHandling will track object references
+        <para>Setting <codeEntityReference>T:Newtonsoft.Json.PreserveReferencesHandling</codeEntityReference> 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" />       
@@ -68,5 +68,8 @@
         the JsonSerializer.</para>
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.PreserveReferencesHandling</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/ReadingWritingJSON.aml b/Doc/ReadingWritingJSON.aml
@@ -5,7 +5,7 @@
       <para>To manually read and write JSON Json.NET provides the
       <codeEntityReference>T:Newtonsoft.Json.JsonReader</codeEntityReference>
       and 
-      <codeEntityReference>T:Newtonsoft.Json.JsonWriter</codeEntityReference> classes.</para>
+      <codeEntityReference>T:Newtonsoft.Json.JsonWriter</codeEntityReference> classes. These are low level classes and used internally by Json.NET.</para>
     </introduction>
     <section>
       <title>JsonTextReader and JsonTextWriter</title>
@@ -33,5 +33,13 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ReadingAndWritingJsonTests.cs" region="ReadingAndWritingJsonLinq" title="Deserializing with JTokenReader" />
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.JsonReader</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonWriter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Linq.JTokenReader</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Linq.JTokenWriter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Bson.BsonReader</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Bson.BsonWriter</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/ReducingSerializedJSONSize.aml b/Doc/ReducingSerializedJSONSize.aml
@@ -123,5 +123,11 @@
 
       </content>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.Formatting</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonIgnoreAttribute</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SelectToken.aml b/Doc/SelectToken.aml
@@ -33,5 +33,14 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="SelectTokenLinq" title="SelectToken With LINQ Example" />
       </content>
     </section>
+    <relatedTopics>
+      <externalLink>
+        <linkText>LINQ to JSON</linkText>
+        <linkUri>LINQtoJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+
+      <codeEntityReference>Overload:Newtonsoft.Json.Linq.JToken.SelectToken</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SerializationAttributes.aml b/Doc/SerializationAttributes.aml
@@ -134,5 +134,12 @@
     </section>
     </sections>
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SerializationCallbacks.aml b/Doc/SerializationCallbacks.aml
@@ -47,22 +47,12 @@ serialization lifecycle, decorate a method with the appropraite attribute
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksExample" title="Serialization Callback Example" />
 
       </content>
-      <!-- If a section contains a sections element, its content creates
-           sub-sections.  These are not collapsible.
-      <sections>
-          <section address="SubSection1">
-              <title>Sub-section 1</title>
-              <content>
-                  <para>Sub-section content.</para>
-              </content>
-          </section>
-          <section address="SubSection2">
-              <title>Sub-section 2</title>
-              <content>
-                  <para>Sub-section content.</para>
-              </content>
-          </section>
-      </sections> -->
     </section>
+    <relatedTopics>
+      <codeEntityReference>T:System.Runtime.Serialization.OnSerializingAttribute</codeEntityReference>
+      <codeEntityReference>T:System.Runtime.Serialization.OnSerializedAttribute</codeEntityReference>
+      <codeEntityReference>T:System.Runtime.Serialization.OnDeserializingAttribute</codeEntityReference>
+      <codeEntityReference>T:System.Runtime.Serialization.OnDeserializedAttribute</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SerializationErrorHandling.aml b/Doc/SerializationErrorHandling.aml
@@ -94,5 +94,14 @@
 
       </content>
     </section>
+    <relatedTopics>
+      <externalLink>
+        <linkText>Serialization Attributes</linkText>
+        <linkUri>SerializationAttributes.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SerializationGuide.aml b/Doc/SerializationGuide.aml
@@ -282,7 +282,26 @@
     </section>
 
       </sections>
-    </section>    
-
+    </section>
+    <relatedTopics>
+      <externalLink>
+        <linkText>Serialization Settings</linkText>
+        <linkUri>SerializationSettings.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <externalLink>
+        <linkText>Serialization Attributes</linkText>
+        <linkUri>SerializationAttributes.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <externalLink>
+        <linkText>Serializing Dates in JSON</linkText>
+        <linkUri>DatesInJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+
+      <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>
diff --git a/Doc/SerializationSettings.aml b/Doc/SerializationSettings.aml
@@ -7,7 +7,8 @@
     </summary>
     -->
     <introduction>
-      <para>JsonSerializer has a number of properties on it to customize how it serializes JSON. These can also be used with the methods on JsonConvert via the JsonSerializerSettings overloads.</para>
+      <para>JsonSerializer has a number of properties on it to customize how it serializes JSON. These can also be used
+      with the methods on JsonConvert via the <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference> overloads.</para>
     </introduction>
 
 <section>
@@ -320,7 +321,25 @@
 </para>
 </content>
 </section>
-
-
+    <relatedTopics>
+      <externalLink>
+        <linkText>Serialization Guide</linkText>
+        <linkUri>SerializationGuide.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <externalLink>
+        <linkText>Serialization Attributes</linkText>
+        <linkUri>SerializationAttributes.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      <externalLink>
+        <linkText>Serializing Dates in JSON</linkText>
+        <linkUri>DatesInJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+
+      <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>
+    </relatedTopics>
   </developerConceptualDocument>
 </topic>