-Merge documentation proof read

Doc/ConditionalProperties.aml

@@ -3,7 +3,7 @@
   <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
     <introduction>
       <para>Json.NET has the ability to conditionally serialize properties by placing a ShouldSerialize method on a class.
-      This funtionality is similar to the <externalLink>
+      This functionality is similar to the <externalLink>
 <linkText>XmlSerializer ShouldSerialize feature</linkText>
 <linkUri>http://msdn.microsoft.com/en-us/library/53b8022e.aspx</linkUri>
 <linkTarget>_blank</linkTarget>
@@ -12,9 +12,9 @@
     <section>
       <title>ShouldSerialize</title>
       <content>
-        <para>To conditionally serialize a property add a boolean method with the same name as the property and then prefixed the method name
+        <para>To conditionally serialize a property, add a method that returns boolean with the same name as the property and then prefix the method name
         with ShouldSerialize. The result of the method determines whether the property is serialized. If the method returns true then the
-        property will be serialized, if it returns false and the property will be skipped.</para>
+        property will be serialized, if it returns false then the property will be skipped.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="EmployeeShouldSerializeExample" title="Employee class with a ShouldSerialize method" />
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConditionalPropertiesTests.cs" region="ShouldSerializeClassTest" title="ShouldSerialize output" />

Doc/ContractResolver.aml

@@ -25,7 +25,7 @@
         <para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.DefaultContractResolver</codeEntityReference>
         is the default resolver used by the
         serializer. It provides many avenues of extensibility in the form of
-        virtual methods that can be overriden.</para>
+        virtual methods that can be overridden.</para>
       </content>
     </section>
     <section>

Doc/ConvertingJSONandXML.aml

@@ -5,7 +5,7 @@
       <para>Json.NET supports converting JSON to XML and vice versa using the
       <codeEntityReference>T:Newtonsoft.Json.Converters.XmlNodeConverter</codeEntityReference>.</para>
       <para>Elements, attributes, text, comments, character data, processing instructions,
-      namespaces and the XML declaration are all preserved when converting between the two. The
+      namespaces, and the XML declaration are all preserved when converting between the two. The
       only caveat is that it is possible to lose the order of differently named nodes at the
       same level when they are grouped together into an array.</para>
     </introduction>
@@ -18,20 +18,20 @@
   <listItem><para>Attributes are prefixed with an @ and should be at the start of the object.</para></listItem>
   <listItem><para>Single child text nodes are a value directly against an element, otherwise they are accessed via #text.</para></listItem>
   <listItem><para>The XML declaration and processing instructions are prefixed with ?.</para></listItem>
-  <listItem><para>Charater data, comments, whitespace and significate whitespace nodes are accessed via
+  <listItem><para>Character data, comments, whitespace and significant whitespace nodes are accessed via
-  #cdata-section, #comment, #whitespace and #significate-whitespace respectively.</para></listItem>
+  #cdata-section, #comment, #whitespace and #significant-whitespace respectively.</para></listItem>
   <listItem><para>Multiple nodes with the same name at the same level are grouped together into an array.</para></listItem>
   <listItem><para>Empty elements are null.</para></listItem>
 </list>
 
-<para>If the XML created from JSON doesn't match what you want then you will need to convert it manually.
+<para>If the XML created from JSON doesn't match what you want, then you will need to convert it manually.
 The best approach to do this is to load your JSON into a LINQ to JSON object like JObject or JArray and then use LINQ to create
 an XDocument. The opposite process, using LINQ with an XDocument to create a JObject or JArray, also works.
-Find out more about using LINQ to JSON with LINQ <link xlink:href="QueryingLINQtoJSON">here</link>.</para>
+You can find out more about using LINQ to JSON with LINQ <link xlink:href="QueryingLINQtoJSON">here</link>.</para>
 
 <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,
+  SerializeXmlNode/DeserializeXmlNode are available when the framework supports XmlDocument;
   SerializeXNode/DeserializeXNode are available when the framework supports XDocument.</para>
 </alert>
 
@@ -47,11 +47,11 @@ Find out more about using LINQ to JSON with LINQ <link xlink:href="QueryingLINQt
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="SerializeXmlNode" title="Converting XML to JSON with SerializeXmlNode" />
 
-       <para>Because multiple nodes with a the same name at the same level are grouped together into an array
+       <para>Because multiple nodes with 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
+       the conversion 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
+       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>
+       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>
 
@@ -64,10 +64,10 @@ Find out more about using LINQ to JSON with LINQ <link xlink:href="QueryingLINQt
    
        <para>The second helper method on JsonConvert is
        <codeEntityReference>Overload:Newtonsoft.Json.JsonConvert.DeserializeXmlNode</codeEntityReference>.
-       This method takes JSON text and deserializes it into a XmlNode.</para>
+       This method takes JSON text and deserializes it into an XmlNode.</para>
    
-       <para>Because valid XML must have one root element the JSON passed to DeserializeXmlNode should
+       <para>Because valid XML must have one root element, the JSON passed to DeserializeXmlNode should
-       have one property in the root JSON object. If the root JSON object has multiple properties then
+       have one property in the root JSON object. If the root JSON object has multiple properties, then
        the overload that also takes an element name should be used. A root element with that name will
        be inserted into the deserialized XmlNode.</para>
 

Doc/CreatingLINQtoJSON.aml

@@ -9,7 +9,7 @@
       <title>Manually Creating JSON</title>
       <content>
         <para>Setting values and creating objects and arrays one at a time gives you
-        total control but it is more verbose than other options.</para>
+        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" />
       </content>
@@ -29,9 +29,9 @@
       <content>
         <para>The last option is to create a JSON object from a non-JSON type using the
         <codeEntityReference>Overload:Newtonsoft.Json.Linq.JObject.FromObject</codeEntityReference>
-        method. Internally FromObject will use the JsonSerializer to serialize the object to LINQ to JSON objects instead of text.</para>
+        method. Internally, FromObject will use the JsonSerializer to serialize the object to LINQ to JSON objects instead of text.</para>
         
-        <para>The example below is creating a JSON object from an anonymous object but any
+        <para>The example below shows creating a JSON object from an anonymous object, but any
         .NET type can be used with FromObject to create JSON.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\LinqToJsonTests.cs" region="LinqToJsonCreateFromObject" title="Creating JSON from an Object" />

Doc/CustomCreationConverter.aml

@@ -18,7 +18,7 @@
       <content>
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="CustomCreationConverterObject" title="CustomCreationConverter" />
         <para>This is an extremely simple example. A more complicated scenario
-        could involve an object factory or service locator which resolves the
+        could involve an object factory or service locator that resolves the
         object at runtime.</para>
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="CustomCreationConverterExample" title="CustomCreationConverter Example" />
       </content>

Doc/DatesInJSON.aml

@@ -13,7 +13,7 @@
 <linkUri>http://www.ietf.org/rfc/rfc4627.txt</linkUri>
 <linkTarget>_blank</linkTarget>
 </externalLink> itself: there is no literal
-      syntax for dates in JSON. The spec has objects, arrays, strings, integers
+      syntax for dates in JSON. The spec has objects, arrays, strings, integers,
       and floats, but it defines no standard for what a date looks like.</para>
     </introduction>
     <!-- Add one or more top-level section elements.  These are collapsible.
@@ -32,12 +32,12 @@
         <para>Prior to Json.NET 4.5 dates were written using the Microsoft
         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
+        older versions of Json.NET, then change the
         <codeEntityReference>T:Newtonsoft.Json.DateFormatHandling</codeEntityReference>
         setting to MicrosoftDateFormat.</para>
         <para>Json.NET also has the <codeEntityReference>T:Newtonsoft.Json.DateTimeZoneHandling</codeEntityReference>
         setting. This can be
-        used to convert DateTime's kind when serializing, e.g. set
+        used to convert a DateTime's kind when serializing. For example set
         DateTimeZoneHandling to Utc to serialize all DateTimes as UTC dates.</para>
       </content>
     </section>
@@ -68,8 +68,8 @@
 <linkUri>http://msdn.microsoft.com/en-us/library/cd9w2te4.aspx</linkUri>
 <linkTarget>_blank</linkTarget>
 </externalLink>: <codeInline>new Date(1234656000000)</codeInline></para>
-        <para>Technically this is invalid JSON according to the spec but all
+        <para>Technically this is invalid JSON according to the spec, but all
-        browsers, and some JSON frameworks, including Json.NET, support it.</para>
+        browsers and some JSON frameworks, including Json.NET, support it.</para>
       </content>
     </section>
     <section>
@@ -77,9 +77,9 @@
       <content>
       <alert class="note">
   <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>
+        format by default, and using this converter is unnecessary.</para>
 </alert>
-        <para>IsoDateTimeConverter seralizes a DateTime to an <externalLink>
+        <para>IsoDateTimeConverter serializes a DateTime to an <externalLink>
 <linkText>ISO 8601</linkText>
 <linkUri>http://en.wikipedia.org/wiki/ISO_8601</linkUri>
 <linkTarget>_blank</linkTarget>

Doc/Introduction.aml

@@ -22,10 +22,10 @@
         <para>LINQ to JSON for manually reading and writing JSON </para>
     </listItem>
    <listItem>
-        <para>High performance, faster than .NET's built-in JSON serializers</para>
+        <para>High performance: faster than .NET's built-in JSON serializers</para>
     </listItem>
    <listItem>
-        <para>Write indented, easy to read JSON</para>
+        <para>Write indented, easy-to-read JSON</para>
     </listItem>
    <listItem>
         <para>Convert JSON to and from XML</para>
@@ -58,15 +58,15 @@ and write from your objects.</para>
 <section>
  <title>History</title>
  <content><para>Json.NET grew out of projects I was working on in late 2005 involving JavaScript,
-            AJAX and .NET. At the time there were no libraries for working with JavaScript in
+            AJAX, and .NET. At the time there were no libraries for working with JavaScript in
-            .NET so I made my own.</para>
+            .NET, so I made my own.</para>
  <para>Starting out as a couple of static methods for escaping JavaScript strings, Json.NET
             evolved as features were added. To add support for reading JSON a major refactor
-            was required and Json.NET will split into the three major classes it still uses
+            was required, and Json.NET was split into the three major classes it still uses
-            today, JsonReader, JsonWriter and JsonSerializer.</para>
+            today: JsonReader, JsonWriter and JsonSerializer.</para>
  <para>Json.NET was first released in June 2006. Since then Json.NET has been downloaded
-            hundreds of thousands of times by developers around the world. It is used in many major open
+            hundreds of thousands of times by developers from around the world. It is used in many major open
-            source projects including <externalLink>
+            source projects, including: <externalLink>
                 <linkText>Mono</linkText>
                 <linkUri>http://www.mono-project.com/</linkUri>
                 <linkTarget>_blank</linkTarget>
@@ -77,7 +77,7 @@ and write from your objects.</para>
                 <linkUri>http://ravendb.net/</linkUri>
                 <linkTarget>_blank</linkTarget>
             </externalLink>,
-            a JSON based documentat database; <externalLink>
+            a JSON based document database; <externalLink>
                 <linkText>ASP.NET SignalR</linkText>
                 <linkUri>http://signalr.net/</linkUri>
                 <linkTarget>_blank</linkTarget>
@@ -93,7 +93,7 @@ and write from your objects.</para>
 
 <section>
  <title>Donate</title>
- <content><para>Json.NET is a personal open source project. Started in 2006, I have put thousands of hours into adding, refining and tuning Json.NET with the goal to make it not just the best JSON serializer for .NET but the best serializer for any computer language. I need your
+ <content><para>Json.NET is a personal open source project. Started in 2006, I have put thousands of hours into adding, refining, and tuning Json.NET with the goal of making it not just the best JSON serializer for .NET, but the best serializer for any computer language. I need your
  help to achieve this.</para>
 
  <markup>

Doc/JsonNetVsWindowsDataJson.aml

@@ -2,11 +2,11 @@
 <topic id="JsonNetVsWindowsDataJson" revisionNumber="1">
   <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
     <introduction>
-      <para>Windows 8 introduces a new way to work with JSON via the <externalLink>
+      <para>Windows 8 introduced a new way to work with JSON via the <externalLink>
 <linkText>Windows.Data.Json</linkText>
 <linkUri>http://msdn.microsoft.com/en-us/library/windows/apps/xaml/br240639.aspx</linkUri>
 <linkTarget>_blank</linkTarget>
-</externalLink> namespace. Similar to LINQ to JSON in Json.NET
+</externalLink> namespace. Similar to LINQ to JSON in Json.NET,
       it defines classes that can be used to parse values, strings, objects, and arrays from
       JSON text or serialize value types into JSON text.</para>
       <para>Below is a comparison of Json.NET&apos;s LINQ to JSON to Window 8&apos;s Windows.Data.Json.</para>
@@ -17,7 +17,7 @@
 <list class="bullet">
    <listItem>
      <para>
-       Runs on .NET 2, .NET 3, .NET 4, Silverlight and Windows Phone 7
+       Runs on .NET 2, .NET 3, .NET 4, Silverlight, and Windows Phone 7
      </para>
    </listItem>
    <listItem>

Doc/JsonSchema.aml

@@ -6,7 +6,7 @@
       and <codeEntityReference>T:Newtonsoft.Json.JsonValidatingReader</codeEntityReference> classes. It sits under
       the <codeEntityReference>N:Newtonsoft.Json.Schema</codeEntityReference> namespace.</para>
       <para>JSON Schema is used to validate the structure and
-      data types of a piece of JSON, similar to XML Schema for XML. Read more about JSON Schema at 
+      data types of a piece of JSON, similar to XML Schema for XML. You can read more about JSON Schema at 
       <externalLink>
         <linkText>json-schema.org</linkText>
         <linkUri>http://json-schema.org/</linkUri>
@@ -36,7 +36,7 @@ method with the JSON Schema.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\JsonSchemaTests.cs" region="IsValidBasic" title="Validate JSON with IsValid" />
 
-<para>To get validation error messages use the
+<para>To get validation error messages, use the
 <codeEntityReference>M:Newtonsoft.Json.Schema.Extensions.IsValid(Newtonsoft.Json.Linq.JToken,Newtonsoft.Json.Schema.JsonSchema,System.Collections.Generic.IList{System.String}@)</codeEntityReference>
 or
 <codeEntityReference>M:Newtonsoft.Json.Schema.Extensions.Validate(Newtonsoft.Json.Linq.JToken,Newtonsoft.Json.Schema.JsonSchema,Newtonsoft.Json.Schema.ValidationEventHandler)</codeEntityReference>
@@ -46,7 +46,7 @@ overloads.</para>
 
 <para>Internally IsValid uses <codeEntityReference>T:Newtonsoft.Json.JsonValidatingReader</codeEntityReference>
 to perform the JSON Schema validation. To skip the overhead of loading JSON into a JObject/JArray, validating
-the JSON and then deserializing the JSON into a class, JsonValidatingReader can be used with JsonSerializer to validate JSON while the object is being deserialized.</para>
+the JSON, and then deserializing the JSON into a class, JsonValidatingReader can be used with JsonSerializer to validate JSON while the object is being deserialized.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\JsonSchemaTests.cs" region="JsonValidatingReader" title="Validate JSON with JsonValidatingReader" />
 

Doc/LINQtoJSON.aml

@@ -3,7 +3,7 @@
   <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
     <introduction>
       <para>LINQ to JSON is an API for working with JSON objects.
-      It has been designed with LINQ in mind to enable to quick querying
+      It has been designed with LINQ in mind to enable quick querying
       and creation of JSON objects. LINQ to JSON sits under the
       <codeEntityReference>N:Newtonsoft.Json.Linq</codeEntityReference>
       namespace.</para>

Doc/Performance.aml

@@ -8,18 +8,18 @@
     <section>
       <title>Optimize Memory Usage</title>
       <content>
-        <para>To keep an application consistantly fast it is important to minimize the
+        <para>To keep an application consistently fast, it is important to minimize the
         amount of time the .NET framework spends performing <externalLink>
 <linkText>garbage collection</linkText>
 <linkUri>http://msdn.microsoft.com/en-us/library/ms973837.aspx</linkUri>
 <linkTarget>_blank</linkTarget>
 </externalLink>.
-        Allocating too many objects, or allocating very large objects can slow down or even
+        Allocating too many objects or allocating very large objects can slow down or even
         halt an application while garbage collection is in progress.
         </para>
-        <para>To minimize memory usage and the number of objects allocated Json.NET supports
+        <para>To minimize memory usage and the number of objects allocated, Json.NET supports
-        serializing and deserializing directly to a stream. Reading or writing JSON a piece at a time instead of having
+        serializing and deserializing directly to a stream. Reading or writing JSON a piece at a time, instead of having
-        the entire JSON string loaded into memory is especially important when working with JSON
+        the entire JSON string loaded into memory, is especially important when working with JSON
         documents greater than 85kb in size to avoid the JSON string ending up in the <externalLink>
 <linkText>large object heap</linkText>
 <linkUri>http://msdn.microsoft.com/en-us/magazine/cc534993.aspx</linkUri>
@@ -35,7 +35,7 @@
       <title>JsonConverters</title>
       <content>
         <para>Passing a <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> to SerializeObject or DeserializeObject provides a simple way to completely
-        change how an object is serialized. There is however a small overhead; the CanConvert method is called for every
+        change how an object is serialized. There is, however, a small amount of overhead; the CanConvert method is called for every
         value to check whether serialization should be handled by that JsonConverter.</para>
         <para>There are a couple of ways to continue to use JsonConverters without any overhead. The simplest way
         is to specify the JsonConverter using the <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>. This attribute tells the serializer
@@ -43,7 +43,7 @@
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterAttribute" title="Use JsonConverter with JsonConverterAttribute" />
 
-        <para>If the class you want to convert isn't your own and you're unable to use an attribute a JsonConverter can still be used by
+        <para>If the class you want to convert isn't your own and you're unable to use an attribute, a JsonConverter can still be used by
         creating your own <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>.</para>
         
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="JsonConverterContractResolver" title="Use JsonConverter with IContractResolver" />
@@ -55,12 +55,12 @@
       <title>Manually Serialize</title>
       <content>
         <para>The absolute fastest way to read and write JSON is to use JsonTextReader/JsonTextWriter directly to manually serialize types.
-        Using a reader or writer directly skips any of the overhead from a serializer such as reflection.</para>
+        Using a reader or writer directly skips any of the overhead from a serializer, such as reflection.</para>
         
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\PerformanceTests.cs" region="ReaderWriter" title="Manually serialize using JsonTextWriter" />
 
         <para>
-          If performance is important and you don't mind more code to get it then this is your best choice. Read more about using JsonReader/JsonWriter here: <link xlink:href="ReadingWritingJSON" />
+          If performance is important and you don't mind writing more code to get it, then this is your best choice. You can read more about using JsonReader/JsonWriter here: <link xlink:href="ReadingWritingJSON" />
         </para>
       </content>
     </section>

Doc/PreserveObjectReferences.aml

@@ -8,15 +8,15 @@
     -->
     <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
+      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
+      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
+      <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
+      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>
@@ -32,14 +32,14 @@
         
 <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
+        <para>The first Person in the list is serialized with the addition of an
-        object Id. The second Person in JSON is now only a reference to the first.</para>
+        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
+        <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>
 <alert class="note">
   <para>References cannot be preserved when a value is set via a non-default constructor.
-        With a non-default constructor child values must be created before the parent value so they can be passed into
+        With a non-default constructor, child values must be created before the parent value so they can be passed into
         the constructor, making tracking reference impossible.
         <codeEntityReference>T:System.Runtime.Serialization.ISerializable</codeEntityReference> types are an example
         of a class whose values are populated with a non-default constructor and won't work with PreserveReferencesHandling.</para>

Doc/QueryingLINQtoJSON.aml

@@ -30,7 +30,7 @@
         
 <alert class="note">
         <para><codeEntityReference>M:Newtonsoft.Json.Linq.JToken.Children</codeEntityReference> returns all the children of a token. If it is a
-        JObject it will return a collection of properties to work with and if
+        JObject it will return a collection of properties to work with, and if
         it is a JArray you will get a collection of the array's values.</para>
 </alert>
 

Doc/ReadingWritingJSON.aml

@@ -2,7 +2,7 @@
 <topic id="ReadingWritingJSON" revisionNumber="1">
   <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
     <introduction>
-      <para>To manually read and write JSON Json.NET provides the
+      <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>
@@ -13,8 +13,8 @@
       <content>
       
 <alert class="note">
-  <para>JsonReader and JsonWriter are low level classes and used internally by Json.NET.
+  <para>JsonReader and JsonWriter are low-level classes and are primarily for internal use by Json.NET.
-    To quickly work with JSON either the serializer - <link xlink:href="SerializingJSON" /> or using <link xlink:href="LINQtoJSON" /> is recommended.
+    To quickly work with JSON, either the serializer - <link xlink:href="SerializingJSON" /> - or using <link xlink:href="LINQtoJSON" /> is recommended.
    </para>
 </alert>
 
@@ -22,13 +22,13 @@
         and <codeEntityReference>T:Newtonsoft.Json.JsonTextWriter</codeEntityReference>
         are used to read and write JSON text.
         The JsonTextWriter has a number of settings on it to control how JSON is formatted
-        when it is written. These options include formatting, indention character, indent
+        when it is written. These options include formatting, indentation character, indent
-        count and quote character.</para>
+        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
+        <para>JsonTextReader has settings on it for reading different date formats, time zones, and
-        the culture used when reading text values.</para>
+        the cultures 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>
@@ -40,7 +40,7 @@
         read and write LINQ to JSON objects. They are located in the
         <codeEntityReference>N:Newtonsoft.Json.Linq</codeEntityReference>
         namespace. These objects allow you to use LINQ to JSON objects with objects that
-        read and write JSON such as the JsonSerializer. For example you can deserialize
+        read and write JSON, such as the JsonSerializer. For example you can deserialize
         from a LINQ to JSON object into a regular .NET object and vice versa.</para>
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ReadingAndWritingJsonTests.cs" region="ReadingAndWritingJsonLinq" title="Deserializing with JTokenReader" />
       </content>

Doc/ReducingSerializedJSONSize.aml

@@ -14,10 +14,10 @@
       <!-- <autoOutline /> -->
       <para>One of the common problems encountered when serializing .NET objects to
       JSON is that the JSON ends up containing a lot of unwanted properties and values.
-      This can be especially important when returning JSON to the client. More JSON
+      This can be especially significant when returning JSON to the client. More JSON
       means more bandwidth and a slower website.</para>
-      <para>To solve the issue of unwanted JSON Json.NET has a range of built in
+      <para>To solve the issue of unwanted JSON, Json.NET has a range of built-in
-      options to fine tune what gets written from a serialized object.</para>
+      options to fine-tune what gets written from a serialized object.</para>
     </introduction>
     <!-- Add one or more top-level section elements.  These are collapsible.
          If using <autoOutline />, add an address attribute to identify it
@@ -27,7 +27,7 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>By default Json.NET will include all of a classes public properties and fields
+        <para>By default Json.NET will include all of a class's public properties and fields
         in the JSON it creates. Adding the
         <codeEntityReference>T:Newtonsoft.Json.JsonIgnoreAttribute</codeEntityReference>
         to a property tells the serializer to always skip writing it to the JSON result.</para>
@@ -35,13 +35,13 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptOut" title="Opt-out Serialization Example" />
         
         <para>If a class has many properties and you only want to serialize a small subset
-        of them then adding JsonIgnore to all the others will be tedious and error prone.
+        of them, then adding JsonIgnore to all the others will be tedious and error prone.
         The way to tackle this scenario is to add the
         <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>
         to the class and
         <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>
         to the properties to serialize. This is opt-in
-        serialization, only the properties you mark up with be serialized, compared to
+        serialization - only the properties you mark up will be serialized, unlike
         opt-out serialization using JsonIgnoreAttribute.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeOptIn" title="Opt-in Serialization Example" />
@@ -53,8 +53,8 @@
         <para>JSON written by the serializer with an option of
         <codeEntityReference>T:Newtonsoft.Json.Formatting</codeEntityReference>
         set to Indented produces
-        nicely formatted, easy to read JSON that is great for readability when you are
+        nicely formatted, easy-to-read JSON that is great for readability when you are
-        developing. Formatting.None on the other hand keeps the JSON result small, skipping
+        developing. <codeInline>Formatting.None</codeInline> on the other hand keeps the JSON result small, skipping
         all unnecessary spaces and line breaks to produce the most compact and efficient
         JSON possible.</para>
       </content>
@@ -72,7 +72,7 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeNullValueHandlingExample" title="NullValueHandling Ignore Example" />
 
         <para>NullValueHandling can also be customized on individual properties
-        using the a
+        using the
         <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
         The JsonPropertyAttribute value of
         NullValueHandling will override the setting on the JsonSerializer for that
@@ -93,9 +93,9 @@
         <para>Json.NET also allows you to customize what the default value of an individual
         property is using the
         <codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference>.
-        For example if a string property called
+        For example, if a string property called
-        Department always returns an empty string in its default state and you didn't want
+        Department always returns an empty string in its default state and you don't want
-        that empty string in your JSON then placing the DefaultValueAttribute on Department
+        that empty string in your JSON, then placing the DefaultValueAttribute on Department
         with that value will mean Department is no longer written to JSON unless it has a
         value.</para>
         
@@ -103,8 +103,7 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="ReducingSerializedJsonSizeDefaultValueHandlingExample" title="DefaultValueHandling Ignore Example" />
         
         <para>DefaultValueHandling can also be customized on individual properties using
-        the a
+        the <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
-        <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>.
         The JsonPropertyAttribute value of DefaultValueHandling
         will override the setting on the JsonSerializer for that property.</para>
       </content>
@@ -112,7 +111,7 @@
     <section>
       <title>IContractResolver</title>
       <content>
-        <para>For more flexibility the
+        <para>For more flexibility, the
         <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>
         provides an interface to customize
         almost every aspect of how a .NET object gets serialized to JSON, including changing

Doc/SerializationAttributes.aml

@@ -15,10 +15,10 @@
       <para>Attributes can be used to control how Json.NET serializes and deserializes .NET objects.</para>
       
 <list class="bullet">
-  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference> - Placed on classes to control how it should be serialized as a JSON object.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonObjectAttribute</codeEntityReference> - Placed on classes to control how they should be serialized as a JSON object.</para></listItem>
-  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> - Placed on collections to control how it should be serialized as a JSON array.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference> - Placed on collections to control how they should be serialized as a JSON array.</para></listItem>
-  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> - Placed on dictionaries to control how it should be serialized as a JSON object.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> - Placed on dictionaries to control how they should be serialized as a JSON object.</para></listItem>
-  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how it should be serialized as a property in a JSON object.</para></listItem>
+  <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference> - Placed on fields and properties to control how they should be serialized as a property in a JSON object.</para></listItem>
   <listItem><para><codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference> - Placed on either classes or fields and properties to specify which JsonConverter should be used during serialization.</para></listItem>
 </list>
 
@@ -32,15 +32,15 @@
         <para>As well as using the built-in Json.NET attributes, Json.NET also looks for the <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
         (if IgnoreSerializableAttribute on DefaultContractResolver is set to false)
         <codeEntityReference>T:System.Runtime.Serialization.DataContractAttribute</codeEntityReference>,
-        <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>
+        <codeEntityReference>T:System.Runtime.Serialization.DataMemberAttribute</codeEntityReference>,
         and <codeEntityReference>T:System.NonSerializedAttribute</codeEntityReference> and attributes when determining how JSON is to be serialized and deserialized.
         </para>
 
         
 <alert class="note">
-  <para>Json.NET attributes take presidence over standard .NET serialization attributes, e.g. if both JsonPropertyAttribute
+  <para>Json.NET attributes take precedence over standard .NET serialization attributes (e.g. if both JsonPropertyAttribute
   and DataMemberAttribute are present on a property and both customize the name,
-  the name from JsonPropertyAttribute will be used.</para>
+  the name from JsonPropertyAttribute will be used).</para>
 </alert>        
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationAttributes" title="Serialization Attributes Example" />
@@ -58,10 +58,10 @@
         <autoOutline /> -->
         <para>The MemberSerialization flag on this attribute specifies whether member serialization is opt-in
         (a member must have the JsonProperty or DataMember attribute to be serialized), opt-out (everything is
-        serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavor) or
+        serialized by default but can be ignored with the JsonIgnoreAttribute, Json.NET's default behavior) or
-        fields (all public and private fields are serialized, properties are ignored).</para>
+        fields (all public and private fields are serialized and properties are ignored).</para>
-        <para>Json.NET serializes .NET classes that implement IEnumerable as an JSON array populated with the
+        <para>Json.NET serializes .NET classes that implement IEnumerable as a JSON array populated with the
-        IEnumerable values. Placing the JsonPropertyAttribute overrides this behavor and forces the serializer
+        IEnumerable values. Placing the JsonPropertyAttribute overrides this behavior and forces the serializer
         to serialize the class's fields and properties.</para>
         <para>The DataContractAttribute can be used as substitute for JsonObjectAttribute. The
         DataContractAttribute will default member serialization to opt-in.</para>
@@ -73,8 +73,8 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>The JsonArrayAttribute and JsonDictionaryAttributes are used to specified whether a class is serialized as that collection type.</para>
+        <para>The JsonArrayAttribute and JsonDictionaryAttributes are used to specify whether a class is serialized as that collection type.</para>
-        <para>The collection attributes have options to customize the JsonConverter, type name handling and reference handling that are applied to collection items.</para>
+        <para>The collection attributes have options to customize the JsonConverter, type name handling, and reference handling that are applied to collection items.</para>
       </content>
     </section>
         
@@ -86,14 +86,14 @@
         <para>JsonPropertyAttribute has a number of uses:</para>
         
 <list class="bullet">
-  <listItem><para>By default the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.</para></listItem>
+  <listItem><para>By default, the JSON property will have the same name as the .NET property. This attribute allows the name to be customized.</para></listItem>
-  <listItem><para>Indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
+  <listItem><para>JsonPropertyAttribute indicates that a property should be serialized when member serialization is set to opt-in.</para></listItem>
-  <listItem><para>Includes non-public properties in serialization and deserialization.</para></listItem>
+  <listItem><para>It includes non-public properties in serialization and deserialization.</para></listItem>
-  <listItem><para>Customize type name, reference, null and default value handling for the property value.</para></listItem>
+  <listItem><para>It can be used to customize type name, reference, null, and default value handling for the property value.</para></listItem>
-  <listItem><para>Customize the property's collection items JsonConverter, type name handing and reference handling.</para></listItem>
+  <listItem><para>It can be used to customize the property's collection items JsonConverter, type name handling, and reference handling.</para></listItem>
 </list>
         
-        <para> The DataMemberAttribute can be used as substitute for JsonPropertyAttribute.</para>
+        <para> The DataMemberAttribute can be used as a substitute for JsonPropertyAttribute.</para>
         
       </content>
     </section>
@@ -114,10 +114,10 @@
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
         <para>The JsonConverterAttribute specifies which JsonSerializer is used to convert an object.</para>
-        <para>The attribute can be placed on a class or a member. When placed on a class the JsonConverter
+        <para>The attribute can be placed on a class or a member. When placed on a class, the JsonConverter
         specified by the attribute will be the default way of serializing that class. When the attribute is
-        on a field or property then the specified JsonConverter will always be used to serialize that value.</para>
+        on a field or property, then the specified JsonConverter will always be used to serialize that value.</para>
-        <para>The priority of which JsonConverter is used is member attribute then class attribute and finally
+        <para>The priority of which JsonConverter is used is member attribute, then class attribute, and finally
         any converters passed to the JsonSerializer.</para>
         
  <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksObject" title="JsonConverter Attribute" />
@@ -126,7 +126,7 @@
         
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationCallbacksExample" title="JsonConverter Example" />
                 
-        <para>To apply a JsonConverter to the items in a collection use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
+        <para>To apply a JsonConverter to the items in a collection, use either <codeEntityReference>T:Newtonsoft.Json.JsonArrayAttribute</codeEntityReference>,
         <codeEntityReference>T:Newtonsoft.Json.JsonDictionaryAttribute</codeEntityReference> or
         <codeEntityReference>T:Newtonsoft.Json.JsonPropertyAttribute</codeEntityReference>
         and set the ItemConverterType property to the converter type you want to use.</para>

Doc/SerializationCallbacks.aml

@@ -22,7 +22,7 @@
 </list>
 <para>
 To tell the serializer which methods should be called during the object's
-serialization lifecycle, decorate a method with the appropraite attribute
+serialization lifecycle, decorate a method with the appropriate attribute
 (<codeEntityReference>T:System.Runtime.Serialization.OnSerializingAttribute</codeEntityReference>,
 <codeEntityReference>T:System.Runtime.Serialization.OnSerializedAttribute</codeEntityReference>,
 <codeEntityReference>T:System.Runtime.Serialization.OnDeserializingAttribute</codeEntityReference>,

Doc/SerializationErrorHandling.aml

@@ -16,8 +16,8 @@
       deserialization. Error handling lets you catch an error and
       choose whether to handle it and continue with serialization or
       let the error bubble up and be thrown in your application.</para>
-      <para>Error handling is defined through two methods: the Error event on
+      <para>Error handling is defined through two methods: the <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference> event on
-      JsonSerializer and the OnErrorAttribute.</para>
+      JsonSerializer and the <codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>.</para>
     </introduction>
     <!-- Add one or more top-level section elements.  These are collapsible.
          If using <autoOutline />, add an address attribute to identify it
@@ -30,7 +30,7 @@
         <para>The <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference>
         event is an event handler found on <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>.
         The error event is raised whenever an exception is thrown while serializing
-        or deserialing JSON. Like all settings found on JsonSerializer it can also
+        or deserializing JSON. Like all settings found on JsonSerializer, it can also
         be set on <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>
         and passed to the serialization methods on JsonConvert.</para>
         
@@ -38,19 +38,19 @@
 
         <para>In this example we are deserializing a JSON array to a collection
         of DateTimes. On the JsonSerializerSettings a handler has been assigned
-        to the Error event which will log the error message and mark the error
+        to the <codeInline>Error</codeInline> event which will log the error message and mark the error
         as handled.</para>
         
         <para>The result of deserializing the JSON is three successfully deserialized
-        dates and three error messages: one for the badly formatted string, "I am
+        dates and three error messages: one for the badly formatted string ("I am
-        not a date and will error!", one for the nested JSON array and one for the
+        not a date and will error!"), one for the nested JSON array, and one for the
         null value since the list doesn't allow nullable DateTimes. The event
         handler has logged these messages and Json.NET has continued on deserializing
         the JSON because the errors were marked as handled.</para>
         
         <para>One thing to note with error handling in Json.NET is that an
         unhandled error will bubble up and raise the event on each of its
-        parents, e.g. an unhandled error when serializing a collection of objects
+        parents. For example an unhandled error when serializing a collection of objects
         will be raised twice, once against the object and then again on the collection.
         This will let you handle an error either where it occurred or on one of its
         parents.</para>
@@ -58,7 +58,7 @@
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandlingWithParent" title="Parent Error Handling" />      
 
         <para>If you aren't immediately handling an error and only want to
-        perform an action against it once then you can check to see whether the
+        perform an action against it once, then you can check to see whether the
         <codeEntityReference>T:Newtonsoft.Json.Serialization.ErrorEventArgs</codeEntityReference>'s
         CurrentObject is equal to the OriginalObject.
         OriginalObject is the object that threw the error and CurrentObject is
@@ -75,13 +75,13 @@
         <para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>
         works much like the other <link xlink:href="SerializationAttributes">.NET serialization attributes</link>
         that Json.NET supports. To use it you simply place the
-        attribute on a method which takes the correct parameters: a
+        attribute on a method that takes the correct parameters: a
-        StreamingContext and a ErrorContext. The name of the method doesn't
+        StreamingContext and an ErrorContext. The name of the method doesn't
         matter.</para>
         
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandlingAttributeObject" title="Serialization Error Handling Attribute" />
         
-        <para>In this example accessing the the Roles property will throw an
+        <para>In this example accessing the Roles property will throw an
         exception when no roles have been set. The HandleError method will set
         the error when serializing Roles as handled and allow Json.NET to
         continue serializing the class.</para>

Doc/SerializationGuide.aml

@@ -18,10 +18,10 @@
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
         <para>At a high level, the Json.NET serializer will convert primitive .NET values into primitive JSON values,
-        .NET arrays and collections to JSON arrays and everything else to JSON objects.</para>
+        will convert .NET arrays and collections to JSON arrays, and will convert everything else to JSON objects.</para>
-        <para>Json.NET will throw an error if it encounters incorrect JSON when deserializing a value. For example if
+        <para>Json.NET will throw an error if it encounters incorrect JSON when deserializing a value. For example, if
         the serializer encounters a JSON property with an array of values and the type of matching .NET property is not
-        a collection then an error will be thrown, and vice-versa.</para>
+        a collection, then an error will be thrown, and vice-versa.</para>
       </content>
     </section>
     <section>
@@ -134,62 +134,62 @@
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
         <para>.NET types that don't fall into any other category listed below
-        (i.e. aren't lists, dictionaries, dynamic, implement ISerializable, etc)
+        (i.e. aren't lists, dictionaries, dynamic, implement ISerializable, etc.)
         are serialized as JSON objects. You can also force a type to be serialized as a JSON object by placing the
         JsonObjectAttribute on the type.</para>
-        <para>By default a type's properties are serialized in opt-out mode. What that means is all public fields and properties with
+        <para>By default a type's properties are serialized in opt-out mode. What that means is that all public fields and properties with
         getters are automatically serialized to JSON, and fields and properties that shouldn't be serialized are opted-out by placing
-        JsonIgnoreAttribute on them. To serialize private members the JsonPropertyAttribute can be placed on private fields and
+        JsonIgnoreAttribute on them. To serialize private members, the JsonPropertyAttribute can be placed on private fields and
         properties.</para>
         <para>Types can also be serialized using opt-in mode. Only properties and fields that have a JsonPropertyAttribute
         or DataMemberAttribute on them will be serialized. Opt-in mode for an object is specified by placing the JsonObjectAttribute
         or DataContractAttribute on the type.</para>
-        <para>Finally types can be serialized using a fields mode. All fields, both public and private, are serialized
+        <para>Finally, types can be serialized using a fields mode. All fields, both public and private, are serialized
         and properties are ignored. This can be specified by setting MemberSerialization.Fields on a type with the JsonObjectAttribute
-        or by the .NET <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
+        or by using the .NET <codeEntityReference>T:System.SerializableAttribute</codeEntityReference>
         and setting IgnoreSerializableAttribute on DefaultContractResolver to false.</para>
       </content>
     </section>   
 
     <section address="Lists">
-      <title>IEnumerable, Lists and Arrays</title>
+      <title>IEnumerable, Lists, and Arrays</title>
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
         <para> .NET lists (types that inherit from IEnumerable) and .NET arrays are converted to JSON arrays. Because JSON
         arrays only support a range of values and not properties, any additional properties and fields declared on .NET
-        collections are not serialized. In situations where a type implements IEnumerable but a JSON array is not wanted then
+        collections are not serialized. In situations where a type implements IEnumerable but a JSON array is not wanted, then
-        the JsonObjectAttribute can be placed the type to force it to be serialized as a JSON object instead.</para>
+        the JsonObjectAttribute can be placed on the type to force it to be serialized as a JSON object instead.</para>
-        <para>JsonArrayAttribute has options on it to customize the JsonConverter, type name handling and reference handling
+        <para>JsonArrayAttribute has options on it to customize the JsonConverter, type name handling, and reference handling
         that are applied to collection items.</para>
-        <para>Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for JSON arrays on the serializer
+        <para>Note that if TypeNameHandling or PreserveReferencesHandling has been enabled for JSON arrays on the serializer,
-        then JSON arrays are wrapped it a containing object. The object will have the type name/reference properties and a
+        then JSON arrays are wrapped in a containing object. The object will have the type name/reference properties and a
-        $values property which will have the collection data.</para>
+        $values property, which will have the collection data.</para>
-        <para>When deserializing if a member is typed as the interface IList&lt;T&gt; then it will be deserialized as a
+        <para>When deserializing, if a member is typed as the interface IList&lt;T&gt;, then it will be deserialized as a
         List&lt;T&gt;.</para>
-        <para>Read more about serializing collections here: <link xlink:href="SerializingCollections" /></para>
+        <para>You can read more about serializing collections here: <link xlink:href="SerializingCollections" /></para>
       </content>
     </section>   
 
     <section address="Dictionarys">
-      <title>Dictionarys and Hashtables</title>
+      <title>Dictionaries and Hashtables</title>
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
         <para>.NET dictionaries (types that inherit from IDictionary) are converted to JSON objects. Note that only the
-        dictionary name/values will be written to the JSON object when serializing and properties on the JSON object will
+        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
+        <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
+        <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
+        <para>When deserializing, if a member is typed as the interface IDictionary&lt;TKey, TValue&gt; then it will be
         deserialized as a Dictionary&lt;TKey, TValue&gt;.</para>
-        <para>Read more about serializing collections here: <link xlink:href="SerializingCollections" /></para>
+        <para>You can read more about serializing collections here: <link xlink:href="SerializingCollections" /></para>
       </content>
     </section>
 
@@ -198,12 +198,12 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>.NET properties on a class that don't specify a type (i.e. they are just object) are serialized as usual. When
+        <para>.NET properties on a class that don't specify a type (i.e. they are just <codeInline>object</codeInline>) are serialized as usual. When
-        untyped properties are deserialized the serializer has no way to know what type to create (unless type name handling
+        untyped properties are deserialized, the serializer has no way of knowing what type to create (unless type name handling
         is enabled and the JSON contains the type names).</para>
-        <para>For these untyped properties the Json.NET serializer will read the JSON into LINQ to JSON objects and set them
+        <para>For these untyped properties, the Json.NET serializer will read the JSON into LINQ to JSON objects and set them
-        to the property. JObject will be created for JSON objects, JArray will be created for JSON arrays and JValue for
+        to the property. JObject will be created for JSON objects; JArray will be created for JSON arrays, and JValue will be
-        primitive JSON values.</para>
+        created for primitive JSON values.</para>
       </content>
     </section>
 
@@ -212,14 +212,14 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>There are two different usages of dynamic (introduced in .NET 4) in .NET. The first are .NET properties with a
+        <para>There are two different usages of <codeInline>dynamic</codeInline> (introduced in .NET 4) in .NET. The first are .NET properties with a
-        type of dynamic. Dynamic proeprties behave like properties declared as object, any value can be assigned to it, but
+        type of dynamic. Dynamic properties behave like properties declared as object: any value can be assigned to it, but
-        the difference being that properties and methods can be called on a dynamic property without casting. In Json.NET
+        the difference being that properties and methods can be called on a dynamic property without casting. In Json.NET,
         dynamic properties are serialized and deserialized exactly the same as untyped objects: because dynamic isn't an actual
-        type Json.NET falls back to deserializing the JSON as LINQ to JSON objects.</para>
+        type, Json.NET falls back to deserializing the JSON as LINQ to JSON objects.</para>
-        <para>The second usage of dynamic in .NET are types that implement
+        <para>The second usage of dynamic in .NET are by the types that implement
         <codeEntityReference>T:System.Dynamic.IDynamicMetaObjectProvider</codeEntityReference>. This interface lets
-        the implementor create dynamic objects that intercept the property and method calls on an object and use them.
+        the implementer create dynamic objects that intercept the property and method calls on an object and use them.
         <codeEntityReference>T:System.Dynamic.ExpandoObject</codeEntityReference>
         is a good example of a dynamic object.</para>
         <para>Dynamic objects are serialized as JSON objects. A property is written for every member name returned by
@@ -227,9 +227,9 @@
         A dynamic object's normal properties aren't serialized by default but can be included by placing the
         JsonPropertyAttribute on them.
         </para>
-        <para>When deserializing dynamic objects the serializer first attempts to set JSON property values on a normal .NET
+        <para>When deserializing dynamic objects, the serializer first attempts to set JSON property values on a normal .NET
-        member with the matching name. If no .NET member is found with the property name then the serializer will call
+        member with the matching name. If no .NET member is found with the property name, then the serializer will call
-        SetMember on the dynamic object. Because there is no type information for dynamic members on a dynamic object the
+        SetMember on the dynamic object. Because there is no type information for dynamic members on a dynamic object, the
         values assigned to them will be LINQ to JSON objects.</para>
       </content>
     </section>
@@ -239,10 +239,10 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>Types that implement ISerializable are serialized as JSON objects. When serializing only the values returned from
+        <para>Types that implement ISerializable are serialized as JSON objects. When serializing, only the values returned from
-        ISerializable.GetObjectData are used; members on the type are ignored. When deserializing the constructor with a
+        ISerializable.GetObjectData are used; members on the type are ignored. When deserializing, the constructor with a
         SerializationInfo and StreamingContext is called, passing the JSON object's values.</para>
-        <para>In situations where this behavior is not wanted the JsonObjectAttribute can be placed on a .NET type that
+        <para>In situations where this behavior is not wanted, the JsonObjectAttribute can be placed on a .NET type that
         implements ISerializable to force it to be serialized as a normal JSON object.</para>
       </content>
     </section>
@@ -252,7 +252,7 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>LINQ to JSON types (e.g. JObject, JArray) are automatically serialized and deserialized to their equivalent JSON
+        <para>LINQ to JSON types (e.g. JObject and JArray) are automatically serialized and deserialized to their equivalent JSON
         when encountered by the Json.NET serializer.</para>
       </content>
     </section>   
@@ -264,15 +264,15 @@
         <autoOutline /> -->
         <para>Serialization of values that are convertible by a <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference>
         (i.e. CanConvert returns true for its type) is
-        completely overridden by the JsonConverter. The test to see whether a value can be converted by a JsonSerializer takes
+        completely overridden by the JsonConverter. The test to see whether a value can be converted by the JsonSerializer takes
         precedence over all other tests.</para>
         <para>JsonConverters can be defined and specified in a number of places: in an attribute on a member, in an attribute
-        on a class and added to the JsonSerializer's converters collection. The priority of which JsonConverter is used is the
+        on a class, and added to the JsonSerializer's converters collection. The priority of which JsonConverter is used is the
-        JsonConverter defined by attribute on a member then the JsonConverter defined by an attribute on a class and finally
+        JsonConverter defined by attribute on a member, then the JsonConverter defined by an attribute on a class, and finally
         any converters passed to the JsonSerializer.</para>
         
 <alert class="note">
-  <para>Because a JsonConverter creates a new value a converter will not work with readonly properties because there is no way to assign the new
+  <para>Because a JsonConverter creates a new value, a converter will not work with readonly properties because there is no way to assign the new
   value to the property. Either change the property to have a public setter or place a JsonPropertyAttribute or DataMemberAttribute on the property.</para>
 </alert>
 

Doc/SerializationTracing.aml

@@ -4,7 +4,7 @@
     <introduction>
       <para>The Json.NET serializer supports logging and debugging using the
       <codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference> interface.
-      By assigning a trace writer you can capture serialization messages and errors, and debug what happens inside the
+      By assigning a trace writer you can capture serialization messages and errors and debug what happens inside the
       Json.NET serializer when serializing and deserializing JSON.</para>
     </introduction>
     <section>
@@ -14,16 +14,16 @@
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\TraceWriterTests.cs" region="MemoryTraceWriterExample" title="Debugging serialization using MemoryTraceWriter" />
         
-        <para>Json.NET has two implementations of ITraceWriter: <codeEntityReference>T:Newtonsoft.Json.Serialization.MemoryTraceWriter</codeEntityReference>
+        <para>Json.NET has two implementations of ITraceWriter: <codeEntityReference>T:Newtonsoft.Json.Serialization.MemoryTraceWriter</codeEntityReference>,
-        which keeps messages in memory for simple debugging like the example
+        which keeps messages in memory for simple debugging, like the example
-        above, and <codeEntityReference>T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter</codeEntityReference> which writes messages to any
+        above, and <codeEntityReference>T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter</codeEntityReference>, which writes messages to any
         System.Diagnostics.TraceListeners your application is using.</para>
       </content>
     </section>
     <section>
       <title>Custom ITraceWriter</title>
       <content>
-        <para>To write messages using your existing logging framework just implement a custom version of ITraceWriter.</para>
+        <para>To write messages using your existing logging framework, just implement a custom version of ITraceWriter.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\TraceWriterTests.cs" region="CustomTraceWriterExample" title="Custom NLog TraceWriter" />
         

Doc/SerializingCollections.aml

@@ -36,7 +36,7 @@
       <content>
         <!-- Uncomment this to create a sub-section outline
         <autoOutline /> -->
-        <para>To deserialize JSON into a .NET collection just specify the collection
+        <para>To deserialize JSON into a .NET collection, just specify the collection
         type you want to deserialize to. Json.NET supports a wide range of collection
         types.</para>
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializingCollectionsDeserializing" title="Deserializing Collections" />

Doc/SerializingJSON.aml

@@ -16,10 +16,10 @@
          at least one procedure or code example -->
 <section>
  <title>JsonConvert</title>
- <content><para>For simple scenarios where you want to convert to and from a JSON string the
+ <content><para>For simple scenarios where you want to convert to and from a JSON string, the
  <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>
+ 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 and Deserializing JSON with JsonConvert" />
 <para>
 	SerializeObject and DeserializeObject both have overloads that take a <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference> object.
@@ -30,19 +30,18 @@
 
 <section>
  <title>JsonSerializer</title>
- <content><para>For more control over how an object is serialized the <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> can be used directly.
+ <content><para>For more control over how an object is serialized, the <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference> can be used directly.
 The JsonSerializer is able to read and write JSON text directly to a stream via <codeEntityReference>T:Newtonsoft.Json.JsonTextReader</codeEntityReference>
 and <codeEntityReference>T:Newtonsoft.Json.JsonTextWriter</codeEntityReference>.
-Other kinds of JsonWriters can also be used such as
+Other kinds of JsonWriters can also be used, such as
-<codeEntityReference>T:Newtonsoft.Json.Linq.JTokenReader</codeEntityReference>/<codeEntityReference>T:Newtonsoft.Json.Linq.JTokenWriter</codeEntityReference>
+<codeEntityReference>T:Newtonsoft.Json.Linq.JTokenReader</codeEntityReference>/<codeEntityReference>T:Newtonsoft.Json.Linq.JTokenWriter</codeEntityReference>,
-to convert your object to and from
+to convert your object to and from LINQ to JSON objects, or
-LINQ to JSON objects or
+<codeEntityReference>T:Newtonsoft.Json.Bson.BsonReader</codeEntityReference>/<codeEntityReference>T:Newtonsoft.Json.Bson.BsonWriter</codeEntityReference>, to convert to and from BSON.</para>
-<codeEntityReference>T:Newtonsoft.Json.Bson.BsonReader</codeEntityReference>/<codeEntityReference>T:Newtonsoft.Json.Bson.BsonWriter</codeEntityReference> to convert to and from BSON.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="JsonSerializerToStream" title="Serializing JSON to a Stream with JsonSerializer" />
 
 <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>Read more about the available JsonSerializer settings here: <link xlink:href="SerializationSettings" /></para>
+<para>You can read more about the available JsonSerializer settings here: <link xlink:href="SerializationSettings" /></para>
 </content>
 </section>
     <relatedTopics>

Doc/SerializingJSONFragments.aml

@@ -4,15 +4,15 @@
 
     <introduction>
       <para>Often when working with large JSON documents you're only interested in a small
-      fragment of information. This scenario can be annoying when you want to serialize
+      fragment of information. This scenario can be annoying when you want to deserialize
-      that Json.NET into .NET objects because you have to define .NET classes for the
+      that JSON fragment into .NET objects because you have to define .NET classes for the
       entire JSON result.</para>
       <para>With Json.NET it is easy to get around this problem. Using LINQ to JSON you
-      can extract the pieces of JSON you want to serialize before passing them to the
+      can extract the pieces of JSON you want to deserialize before passing them to the
       Json.NET serializer.</para>
 
 <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializingPartialJsonFragmentsObject" title="Fragments Object" />
-<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializingPartialJsonFragmentsExample" title="Serializing Partial JSON Fragment Example" />
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializingPartialJsonFragmentsExample" title="Deserializing Partial JSON Fragment Example" />
 
     </introduction>
     <relatedTopics>

Doc/doc.content

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Topics>
   <Topic id="Introduction" visible="True" isDefault="true" />
-  <Topic id="SerializingJSON" visible="True" title="Serializing and Deserializing JSON">
+  <Topic id="SerializingJSON" visible="True" isExpanded="true" title="Serializing and Deserializing JSON">
     <Topic id="SerializationSettings" visible="True" title="Serialization Settings" />
     <Topic id="SerializationGuide" visible="True" title="Serialization Guide" />
     <Topic id="SerializationAttributes" visible="True" title="Serialization Attributes" />
@@ -12,7 +12,7 @@
     <Topic id="SerializingCollections" visible="True" title="Serializing Collections" />
     <Topic id="DatesInJSON" visible="True" title="Serializing Dates in JSON" />
     <Topic id="ReducingSerializedJSONSize" visible="True" title="Reducing Serialized JSON Size" />
-    <Topic id="SerializingJSONFragments" visible="True" title="Serializing Partial JSON Fragments" />
+    <Topic id="SerializingJSONFragments" visible="True" isSelected="true" title="Deserializing Partial JSON Fragments" />
     <Topic id="ConditionalProperties" visible="True" title="Conditional Property Serialization" />
     <Topic id="ContractResolver" visible="True" title="Serialization using ContractResolver" />
     <Topic id="SerializationTracing" visible="True" title="Debugging with Serialization Tracing" />
@@ -29,8 +29,8 @@
   <Topic id="ConvertingJSONandXML" visible="True" title="Converting between JSON and XML" />
   <Topic id="JsonNetVsDotNetSerializers" visible="True" title="Json.NET vs .NET Serializers" />
   <Topic id="JsonNetVsWindowsDataJson" visible="True" title="Json.NET vs Windows.Data.Json" />
-  <Topic id="Samples" visible="True" isExpanded="true" title="Samples">
+  <Topic id="Samples" visible="True" title="Samples">
-    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" isExpanded="true" title="Serializing JSON">
+    <Topic id="d6e185d5-c992-44fc-8d8f-d9acc2bbec2f" visible="True" noFile="true" title="Serializing JSON">
       <Topic id="SerializeObject" visible="True" title="Serialize an Object" />
       <Topic id="SerializeCollection" visible="True" title="Serialize a Collection" />
       <Topic id="SerializeDictionary" visible="True" title="Serialize a Dictionary" />
@@ -53,7 +53,7 @@
       <Topic id="DefaultValueHandlingIgnore" visible="True" title="DefaultValueHandling setting" />
       <Topic id="DeserializeMissingMemberHandling" visible="True" title="MissingMemberHandling setting" />
       <Topic id="NullValueHandlingIgnore" visible="True" title="NullValueHandling setting" />
-      <Topic id="ReferenceLoopHandlingIgnore" visible="True" isSelected="true" title="ReferenceLoopHandling setting" />
+      <Topic id="ReferenceLoopHandlingIgnore" visible="True" title="ReferenceLoopHandling setting" />
       <Topic id="PreserveReferencesHandlingObject" visible="True" title="PreserveReferencesHandling setting" />
       <Topic id="SerializeDateFormatHandling" visible="True" title="DateFormatHandling setting" />
       <Topic id="SerializeDateTimeZoneHandling" visible="True" title="DateTimeZoneHandling setting" />