-Improved documentation

2012-07-27 22:57:08 +12:00
parent 2097219ec9
commit 29f1ed9cd0
18 changed files with 173 additions and 46 deletions
@@ -9,13 +9,26 @@
      namespace.</para>
    </introduction>
    
+    <section>
+      <title>Reading JSON</title>
+      <content>
+        <para>JSON values can be read from a string use the
+        <codeEntityReference>M:Newtonsoft.Json.Linq.JToken.Parse(System.String)</codeEntityReference>
+        method.</para>
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateParse" title="Parsing a JSON Object from Text" />
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateParseArray" title="Parsing a JSON Array from Text" />
+      </content>
+    </section>
    <section>
      <title>Creating JSON</title>
      <content>
        <!-- Uncomment this to create a sub-section outline
        <autoOutline /> -->
        <para>There are a number of different options when it comes to creating
-        JSON using LINQ to JSON. The first to create objects imperatively. You
+        JSON using LINQ to JSON.</para>
+        
+        <para>The first to create objects imperatively. You
        have total control but it is more verbose than other options.</para>
        
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateNormal" title="Creating JSON" />
@@ -24,17 +37,12 @@

 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateDeclaratively" title="Creating JSON Declaratively" />

-        <para>You can create a JSON object from a non-JSON type using the
+        <para>Finally you can create a JSON object from a non-JSON type using the
        <codeEntityReference>Overload:Newtonsoft.Json.Linq.JObject.FromObject</codeEntityReference>
-        method.</para>
+        method. The example below is creating a JSON object from an anonymous object but any
+        .NET type can be used with FromObject.</para>

-<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateFromObject" title="Creating JSON From An Object" />
-
-        <para>Finally JSON objects can be created from a string use the
-        <codeEntityReference>M:Newtonsoft.Json.Linq.JToken.Parse(System.String)</codeEntityReference>
-        method.</para>
-
-<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateParse" title="Creating JSON From Text" />
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateFromObject" title="Creating JSON from an Object" />
      </content>
    </section>
    <section>
@@ -5,11 +5,29 @@
      <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. These are low level classes and used internally by Json.NET.</para>
+      <codeEntityReference>T:Newtonsoft.Json.JsonWriter</codeEntityReference> classes.</para>
+
    </introduction>
    <section>
      <title>JsonTextReader and JsonTextWriter</title>
      <content>
+      
+<alert class="note">
+  <para>JsonReader and JsonWriter are low level classes and used internally by Json.NET.
+    To quickly work with JSON either the serializer -
+      <externalLink>
+        <linkText>Serializing and Deserializing JSON</linkText>
+        <linkUri>SerializingJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
+      or using <externalLink>
+        <linkText>LINQ to JSON</linkText>
+        <linkUri>LINQtoJSON.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink> is recommended.
+   </para>
+</alert>
+
        <para><codeEntityReference>T:Newtonsoft.Json.JsonTextReader</codeEntityReference>
        and <codeEntityReference>T:Newtonsoft.Json.JsonTextWriter</codeEntityReference>
        are used to read and write JSON text.
@@ -18,6 +36,10 @@
        count and quote character.</para>

 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ReadingAndWritingJsonTests.cs" region="ReadingAndWritingJsonText" title="Writing JSON with JsonTextWriter" />
+
+        <para>JsonTextReader has settings on it for reading different date formats and time zones, and
+        the culture used when reading text values.</para>
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ReadingAndWritingJsonTests.cs" region="ReadingJsonText" title="Reading JSON with JsonTextReader" />
      </content>
    </section>
    <section>
@@ -193,6 +193,11 @@
        dictionary name/values will be written to the JSON object when serializing and properties on the JSON object will
        be added to the dictionary's name/values when deserializing. Additional members on the .NET dictionary are ignored
        during serialization.</para>
+        <para>When serializing a dictionary the keys of the dictionary are converted to strings and used as the
+        JSON object property names. The string written for a key can be customized by either overriding
+        <codeEntityReference>M:System.Object.ToString</codeEntityReference> for the key type or by implementing a
+        <codeEntityReference>T:System.ComponentModel.TypeConverter</codeEntityReference>. A TypeConverter will also
+        support converting a custom string back again when deserializing a dictionary.</para>
        <para>JsonDictionaryAttribute has options on it to customize the JsonConverter, type name handling and reference
        handling that are applied to collection items.</para>
        <para>When deserializing if a member is typed as the interface IDictionary&lt;TKey, TValue&gt; then it will be
@@ -13,7 +13,7 @@

 <section>
 <title>DateFormatHandling</title>
- <content><para>DateFormatHandling controls how dates are serialized.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference> controls how dates are serialized.</para>
 
 <table>
  <tableHeader>
@@ -24,11 +24,11 @@
  </tableHeader>
  <row>
    <entry><para><legacyBold>IsoDateFormat</legacyBold></para></entry>
-    <entry><para>By default Json.NET writes dates in the ISO 8601 format, e.g. "2012-03-21T05:40Z".</para></entry>
+    <entry><para>By default Json.NET writes dates in the ISO 8601 format, e.g. <codeInline>"2012-03-21T05:40Z"</codeInline>.</para></entry>
  </row>
  <row>
    <entry><para><legacyBold>MicrosoftDateFormat</legacyBold></para></entry>
-    <entry><para>Dates are written in the Microsoft JSON format, e.g. "\/Date(1198908717056)\/".</para></entry>
+    <entry><para>Dates are written in the Microsoft JSON format, e.g. <codeInline>"\/Date(1198908717056)\/"</codeInline>.</para></entry>
  </row>
 </table>

@@ -37,7 +37,7 @@

 <section>
 <title>MissingMemberHandling</title>
- <content><para>MissingMemberHandling controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.MissingMemberHandling</codeEntityReference> controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.</para>
 
 <table>
  <tableHeader>
@@ -61,7 +61,7 @@

 <section>
 <title>ReferenceLoopHandling</title>
- <content><para>ReferenceLoopHandling controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.ReferenceLoopHandling</codeEntityReference> controls how circular referencing objects, e.g. a Person object referencing itself via a Manager property, are serialized.</para>
 
 <table>
  <tableHeader>
@@ -89,7 +89,7 @@

 <section>
 <title>NullValueHandling</title>
- <content><para>NullValueHandling controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference> controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization.</para>
 
 <table>
  <tableHeader>
@@ -114,7 +114,7 @@

 <section>
 <title>DefaultValueHandling</title>
- <content><para>DefaultValueHandling controls how Json.NET uses default values set using the .NET DefaultValueAttribute when serializing and deserializing.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference> controls how Json.NET uses default values set using the .NET <codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference> when serializing and deserializing.</para>
 
 <table>
  <tableHeader>
@@ -139,7 +139,7 @@

 <section>
 <title>ObjectCreationHandling</title>
- <content><para>ObjectCreationHandling controls how objects are created and deserialized to during deserialization.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.ObjectCreationHandling</codeEntityReference> controls how objects are created and deserialized to during deserialization.</para>
 
 <table>
  <tableHeader>
@@ -168,7 +168,7 @@

 <section>
 <title>TypeNameHandling</title>
- <content><para>TypeNameHandling controls whether Json.NET includes .NET type names during serialization with a $type property and reads .NET type names from that property to determine what type to create during deserialization.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.TypeNameHandling</codeEntityReference> controls whether Json.NET includes .NET type names during serialization with a $type property and reads .NET type names from that property to determine what type to create during deserialization.</para>
 
 <table>
  <tableHeader>
@@ -205,7 +205,7 @@

 <section>
 <title>TypeNameAssemblyFormat</title>
- <content><para>TypeNameAssemblyFormat controls how type names are written during serialization.</para>
+ <content><para><codeEntityReference>T:System.Runtime.Serialization.Formatters.FormatterAssemblyStyle</codeEntityReference> controls how type names are written during serialization.</para>
 
 <table>
  <tableHeader>
@@ -230,14 +230,14 @@

 <section>
 <title>Binder</title>
- <content><para>The serialization binder is used to resolve type names to a .NET type.</para>
+ <content><para>The <codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference> is used to resolve type names to a .NET type.</para>
 <para>Read more about the serialization binder here: <codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference></para>
 </content>
 </section>

 <section>
 <title>ConstructorHandling</title>
- <content><para>ConstructorHandling controls how constructors are used when initializing objects during deserialization.</para>
+ <content><para><codeEntityReference>T:Newtonsoft.Json.ConstructorHandling</codeEntityReference> controls how constructors are used when initializing objects during deserialization.</para>
 
 <table>
  <tableHeader>
@@ -265,7 +265,7 @@
 <section>
 <title>Converters</title>
 <content><para>This is the collection of JsonConverters that will be used during serialization and deserialization.</para>
- <para>JsonConverters allows JSON to be manually written during serialization and read during deserialization.
+ <para>A <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> allows JSON to be manually written during serialization and read during deserialization.
 This is useful for particularly complex JSON structures or for when you want to change how a type is serialized.</para>
 <para>When a JsonConverter has been added to a JsonSerializer it will be checked for every value that is being serialized/deserialized
 using its CanConvert to see if it should be used. If CanConvert returns true then the JsonConverter will be used to read or write
@@ -300,7 +300,8 @@
 <section>
 <title>ContractResolver</title>
 <content><para>Internally for every .NET type the JsonSerializer will create a contract of how the type should be serialized and deserialized,
- based on type metadata and attributes applied to the class. Specifying a custom IContractResolver allows the creation of contracts to be customized.</para>
+ based on type metadata and attributes applied to the class. Specifying a custom <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
+ allows the creation of contracts to be customized.</para>
 <para>Read more about Contract Resolvers here: <externalLink>
 <linkText>Contract Resolvers</linkText>
 <linkUri>ContractResolver.htm</linkUri>
@@ -311,7 +312,7 @@

 <section>
 <title>Error</title>
- <content><para>The Error event can catch errors during serialization and either handle the event and continue with
+ <content><para>The <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference> event can catch errors during serialization and either handle the event and continue with
 serialization or let the error bubble up and be thrown to the application.</para>
 <para>Read more about error handling here: <externalLink>
 <linkText>Serialization Error Handling</linkText>
@@ -337,9 +338,11 @@
        <linkUri>DatesInJSON.htm</linkUri>
        <linkTarget>_self</linkTarget>
      </externalLink>
-
+      
      <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference>
+      <codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference>
    </relatedTopics>
  </developerConceptualDocument>
 </topic>
@@ -54,6 +54,11 @@
      </content>
    </section>
    <relatedTopics>
+      <externalLink>
+        <linkText>Serialization Guide</linkText>
+        <linkUri>SerializationGuide.htm</linkUri>
+        <linkTarget>_self</linkTarget>
+      </externalLink>
      <codeEntityReference>T:Newtonsoft.Json.JsonConvert</codeEntityReference>
      <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
    </relatedTopics>
@@ -19,7 +19,7 @@
 <codeEntityReference>Overload:Newtonsoft.Json.JsonConvert.SerializeObject</codeEntityReference> and
 <codeEntityReference>Overload:Newtonsoft.Json.JsonConvert.DeserializeObject</codeEntityReference>
 methods on JsonConvert provide an easy to use wrapper over JsonSerializer.</para>
- <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializeObject" title="Serializing JSON with JsonConvert" />
+ <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializeObject" title="Serializing and Deserializing JSON with JsonConvert" />
 <para>
 	SerializeObject and DeserializeObject both have overloads that take a <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference> object.
 	JsonSerializerSettings lets you use many of the JsonSerializer settings listed below while still using the simple serialization methods.