Merge pull request #1098 from stakx/issue-1097-clean-up-xml-documentation-comments

Fix minor issues in XML documentation comments

Src/Newtonsoft.Json/Bson/BsonReader.cs

@@ -85,7 +85,7 @@ namespace Newtonsoft.Json.Bson
         }
 
         /// <summary>
-        /// Gets or sets a value indicating whether binary data reading should compatible with incorrect Json.NET 3.5 written binary.
+        /// Gets or sets a value indicating whether binary data reading should be compatible with incorrect Json.NET 3.5 written binary.
         /// </summary>
         /// <value>
         /// 	<c>true</c> if binary data reading will be compatible with incorrect Json.NET 3.5 written binary; otherwise, <c>false</c>.

Src/Newtonsoft.Json/Bson/BsonWriter.cs

@@ -103,7 +103,7 @@ namespace Newtonsoft.Json.Bson
         }
 
         /// <summary>
-        /// Writes out a comment <code>/*...*/</code> containing the specified text.
+        /// Writes a comment <c>/*...*/</c> containing the specified text.
         /// </summary>
         /// <param name="text">Text to place inside the comment.</param>
         public override void WriteComment(string text)

Src/Newtonsoft.Json/ConstructorHandling.cs

@@ -31,7 +31,7 @@ namespace Newtonsoft.Json
     public enum ConstructorHandling
     {
         /// <summary>
-        /// First attempt to use the public default constructor, then fall back to single parameterized constructor, then the non-public default constructor.
+        /// First attempt to use the public default constructor, then fall back to a single parameterized constructor, then to the non-public default constructor.
         /// </summary>
         Default = 0,
 

Src/Newtonsoft.Json/Converters/CustomCreationConverter.cs

@@ -30,7 +30,7 @@ using Newtonsoft.Json.Utilities;
 namespace Newtonsoft.Json.Converters
 {
     /// <summary>
-    /// Create a custom object
+    /// Creates a custom object.
     /// </summary>
     /// <typeparam name="T">The object type to convert.</typeparam>
     public abstract class CustomCreationConverter<T> : JsonConverter

Src/Newtonsoft.Json/Converters/EntityKeyMemberConverter.cs

@@ -32,7 +32,7 @@ using Newtonsoft.Json.Utilities;
 namespace Newtonsoft.Json.Converters
 {
     /// <summary>
-    /// Converts an Entity Framework EntityKey to and from JSON.
+    /// Converts an Entity Framework <c>EntityKey</c> to and from JSON.
     /// </summary>
     public class EntityKeyMemberConverter : JsonConverter
     {

Src/Newtonsoft.Json/Converters/ExpandoObjectConverter.cs

@@ -36,7 +36,7 @@ using Newtonsoft.Json.Utilities;
 namespace Newtonsoft.Json.Converters
 {
     /// <summary>
-    /// Converts an ExpandoObject to and from JSON.
+    /// Converts an <see cref="ExpandoObject"/> to and from JSON.
     /// </summary>
     public class ExpandoObjectConverter : JsonConverter
     {

Src/Newtonsoft.Json/Converters/XmlNodeConverter.cs

@@ -986,9 +986,9 @@ namespace Newtonsoft.Json.Converters
         private const string JsonNamespaceUri = "http://james.newtonking.com/projects/json";
 
         /// <summary>
-        /// Gets or sets the name of the root element to insert when deserializing to XML if the JSON structure has produces multiple root elements.
+        /// Gets or sets the name of the root element to insert when deserializing to XML if the JSON structure has produced multiple root elements.
         /// </summary>
-        /// <value>The name of the deserialize root element.</value>
+        /// <value>The name of the deserialized root element.</value>
         public string DeserializeRootElementName { get; set; }
 
         /// <summary>
@@ -2004,7 +2004,7 @@ namespace Newtonsoft.Json.Converters
         }
 
         /// <summary>
-        /// Checks if the attributeName is a namespace attribute.
+        /// Checks if the <paramref name="attributeName"/> is a namespace attribute.
         /// </summary>
         /// <param name="attributeName">Attribute name to test.</param>
         /// <param name="prefix">The attribute name prefix if it has one, otherwise an empty string.</param>

Src/Newtonsoft.Json/DefaultValueHandling.cs

@@ -46,7 +46,7 @@ namespace Newtonsoft.Json
 
         /// <summary>
         /// Ignore members where the member value is the same as the member's default value when serializing objects
-        /// so that is is not written to JSON.
+        /// so that it is not written to JSON.
         /// This option will ignore all default values (e.g. <c>null</c> for objects and nullable types; <c>0</c> for integers,
         /// decimals and floating point numbers; and <c>false</c> for booleans). The default value ignored can be changed by
         /// placing the <see cref="DefaultValueAttribute"/> on the property.
@@ -60,7 +60,7 @@ namespace Newtonsoft.Json
 
         /// <summary>
         /// Ignore members where the member value is the same as the member's default value when serializing objects
-        /// and sets members to their default value when deserializing.
+        /// and set members to their default value when deserializing.
         /// </summary>
         IgnoreAndPopulate = Ignore | Populate
     }

Src/Newtonsoft.Json/FloatFormatHandling.cs

@@ -37,7 +37,7 @@ namespace Newtonsoft.Json
         String = 0,
 
         /// <summary>
-        /// Write special floating point values as symbols in JSON, e.g. NaN, Infinity, -Infinity.
+        /// Write special floating point values as symbols in JSON, e.g. "NaN", "Infinity", "-Infinity".
         /// Note that this will produce non-valid JSON.
         /// </summary>
         Symbol = 1,

Src/Newtonsoft.Json/FormatterAssemblyStyle.cs

@@ -9,7 +9,7 @@ namespace System.Runtime.Serialization.Formatters
     public enum FormatterAssemblyStyle
     {
         /// <summary>
-        /// In simple mode, the assembly used during deserialization need not match exactly the assembly used during serialization. Specifically, the version numbers need not match as the LoadWithPartialName method is used to load the assembly.
+        /// In simple mode, the assembly used during deserialization need not match exactly the assembly used during serialization. Specifically, the version numbers need not match as the <c>LoadWithPartialName</c> method is used to load the assembly.
         /// </summary>
         Simple = 0,
 

Src/Newtonsoft.Json/IArrayPool.cs

@@ -7,7 +7,7 @@
     public interface IArrayPool<T>
     {
         /// <summary>
-        /// Rent a array from the pool. This array must be returned when it is no longer needed.
+        /// Rent an array from the pool. This array must be returned when it is no longer needed.
         /// </summary>
         /// <param name="minimumLength">The minimum required length of the array. The returned array may be longer.</param>
         /// <returns>The rented array from the pool. This array must be returned when it is no longer needed.</returns>

Src/Newtonsoft.Json/IJsonLineInfo.cs

@@ -34,20 +34,20 @@ namespace Newtonsoft.Json
         /// Gets a value indicating whether the class can return line information.
         /// </summary>
         /// <returns>
-        /// 	<c>true</c> if LineNumber and LinePosition can be provided; otherwise, <c>false</c>.
+        /// 	<c>true</c> if <see cref="LineNumber"/> and <see cref="LinePosition"/> can be provided; otherwise, <c>false</c>.
         /// </returns>
         bool HasLineInfo();
 
         /// <summary>
         /// Gets the current line number.
         /// </summary>
-        /// <value>The current line number or 0 if no line information is available (for example, HasLineInfo returns false).</value>
+        /// <value>The current line number or 0 if no line information is available (for example, when <see cref="HasLineInfo"/> returns <c>false</c>).</value>
         int LineNumber { get; }
 
         /// <summary>
         /// Gets the current line position.
         /// </summary>
-        /// <value>The current line position or 0 if no line information is available (for example, HasLineInfo returns false).</value>
+        /// <value>The current line position or 0 if no line information is available (for example, when <see cref="HasLineInfo"/> returns <c>false</c>).</value>
         int LinePosition { get; }
     }
 }

Src/Newtonsoft.Json/JsonArrayAttribute.cs

@@ -53,7 +53,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="JsonObjectAttribute"/> class with a flag indicating whether the array can contain null items
+        /// Initializes a new instance of the <see cref="JsonObjectAttribute"/> class with a flag indicating whether the array can contain null items.
         /// </summary>
         /// <param name="allowNullItems">A flag indicating whether the array can contain null items.</param>
         public JsonArrayAttribute(bool allowNullItems)

Src/Newtonsoft.Json/JsonContainerAttribute.cs

@@ -59,13 +59,15 @@ namespace Newtonsoft.Json
         public Type ItemConverterType { get; set; }
 
         /// <summary>
-        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by ItemConverterType.
+        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by <see cref="ItemConverterType"/>.
         /// If null, the default constructor is used.
         /// When non-null, there must be a constructor defined in the <see cref="JsonConverter"/> that exactly matches the number,
         /// order, and type of these parameters.
         /// </summary>
         /// <example>
+        /// <code>
         /// [JsonContainer(ItemConverterType = typeof(MyContainerConverter), ItemConverterParameters = new object[] { 123, "Four" })]
+        /// </code>
         /// </example>
         public object[] ItemConverterParameters { get; set; }
 
@@ -84,13 +86,15 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// The parameter list to use when constructing the <see cref="NamingStrategy"/> described by NamingStrategyType.  
+        /// The parameter list to use when constructing the <see cref="NamingStrategy"/> described by <see cref="NamingStrategyType"/>.
         /// If null, the default constructor is used.
         /// When non-null, there must be a constructor defined in the <see cref="NamingStrategy"/> that exactly matches the number,
         /// order, and type of these parameters.
         /// </summary>
         /// <example>
+        /// <code>
         /// [JsonContainer(NamingStrategyType = typeof(MyNamingStrategy), NamingStrategyParameters = new object[] { 123, "Four" })]
+        /// </code>
         /// </example>
         public object[] NamingStrategyParameters
         {

Src/Newtonsoft.Json/JsonConvert.cs

@@ -46,7 +46,7 @@ using System.Xml.Linq;
 namespace Newtonsoft.Json
 {
     /// <summary>
-    /// Provides methods for converting between common language runtime types and JSON types.
+    /// Provides methods for converting between .NET types and JSON types.
     /// </summary>
     /// <example>
     ///   <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializeObject" title="Serializing and Deserializing JSON with JsonConvert" />
@@ -63,22 +63,22 @@ namespace Newtonsoft.Json
         public static Func<JsonSerializerSettings> DefaultSettings { get; set; }
 
         /// <summary>
-        /// Represents JavaScript's boolean value true as a string. This field is read-only.
+        /// Represents JavaScript's boolean value <c>true</c> as a string. This field is read-only.
         /// </summary>
         public static readonly string True = "true";
 
         /// <summary>
-        /// Represents JavaScript's boolean value false as a string. This field is read-only.
+        /// Represents JavaScript's boolean value <c>false</c> as a string. This field is read-only.
         /// </summary>
         public static readonly string False = "false";
 
         /// <summary>
-        /// Represents JavaScript's null as a string. This field is read-only.
+        /// Represents JavaScript's <c>null</c> as a string. This field is read-only.
         /// </summary>
         public static readonly string Null = "null";
 
         /// <summary>
-        /// Represents JavaScript's undefined as a string. This field is read-only.
+        /// Represents JavaScript's <c>undefined</c> as a string. This field is read-only.
         /// </summary>
         public static readonly string Undefined = "undefined";
 
@@ -93,7 +93,7 @@ namespace Newtonsoft.Json
         public static readonly string NegativeInfinity = "-Infinity";
 
         /// <summary>
-        /// Represents JavaScript's NaN as a string. This field is read-only.
+        /// Represents JavaScript's <c>NaN</c> as a string. This field is read-only.
         /// </summary>
         public static readonly string NaN = "NaN";
 
@@ -762,7 +762,7 @@ namespace Newtonsoft.Json
         /// </summary>
         /// <typeparam name="T">
         /// The anonymous type to deserialize to. This can't be specified
-        /// traditionally and must be infered from the anonymous type passed
+        /// traditionally and must be inferred from the anonymous type passed
         /// as a parameter.
         /// </typeparam>
         /// <param name="value">The JSON to deserialize.</param>
@@ -778,7 +778,7 @@ namespace Newtonsoft.Json
         /// </summary>
         /// <typeparam name="T">
         /// The anonymous type to deserialize to. This can't be specified
-        /// traditionally and must be infered from the anonymous type passed
+        /// traditionally and must be inferred from the anonymous type passed
         /// as a parameter.
         /// </typeparam>
         /// <param name="value">The JSON to deserialize.</param>
@@ -872,7 +872,7 @@ namespace Newtonsoft.Json
         /// <typeparam name="T">The type of the object to deserialize to.</typeparam>
         /// <param name="value">The JSON to deserialize.</param>
         /// <returns>
-        /// A task that represents the asynchronous deserialize operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
+        /// A task that represents the asynchronous deserialization operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
         /// </returns>
         [ObsoleteAttribute("DeserializeObjectAsync is obsolete. Use the Task.Factory.StartNew method to deserialize JSON asynchronously: Task.Factory.StartNew(() => JsonConvert.DeserializeObject<T>(value))")]
         public static Task<T> DeserializeObjectAsync<T>(string value)
@@ -891,7 +891,7 @@ namespace Newtonsoft.Json
         /// If this is null, default serialization settings will be used.
         /// </param>
         /// <returns>
-        /// A task that represents the asynchronous deserialize operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
+        /// A task that represents the asynchronous deserialization operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
         /// </returns>
         [ObsoleteAttribute("DeserializeObjectAsync is obsolete. Use the Task.Factory.StartNew method to deserialize JSON asynchronously: Task.Factory.StartNew(() => JsonConvert.DeserializeObject<T>(value, settings))")]
         public static Task<T> DeserializeObjectAsync<T>(string value, JsonSerializerSettings settings)
@@ -905,7 +905,7 @@ namespace Newtonsoft.Json
         /// </summary>
         /// <param name="value">The JSON to deserialize.</param>
         /// <returns>
-        /// A task that represents the asynchronous deserialize operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
+        /// A task that represents the asynchronous deserialization operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
         /// </returns>
         [ObsoleteAttribute("DeserializeObjectAsync is obsolete. Use the Task.Factory.StartNew method to deserialize JSON asynchronously: Task.Factory.StartNew(() => JsonConvert.DeserializeObject(value))")]
         public static Task<object> DeserializeObjectAsync(string value)
@@ -924,7 +924,7 @@ namespace Newtonsoft.Json
         /// If this is null, default serialization settings will be used.
         /// </param>
         /// <returns>
-        /// A task that represents the asynchronous deserialize operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
+        /// A task that represents the asynchronous deserialization operation. The value of the <c>TResult</c> parameter contains the deserialized object from the JSON string.
         /// </returns>
         [ObsoleteAttribute("DeserializeObjectAsync is obsolete. Use the Task.Factory.StartNew method to deserialize JSON asynchronously: Task.Factory.StartNew(() => JsonConvert.DeserializeObject(value, type, settings))")]
         public static Task<object> DeserializeObjectAsync(string value, Type type, JsonSerializerSettings settings)
@@ -993,7 +993,7 @@ namespace Newtonsoft.Json
         #region Xml
 #if !(PORTABLE40 || PORTABLE || DOTNET)
         /// <summary>
-        /// Serializes the XML node to a JSON string.
+        /// Serializes the <see cref="XmlNode"/> to a JSON string.
         /// </summary>
         /// <param name="node">The node to serialize.</param>
         /// <returns>A JSON string of the XmlNode.</returns>
@@ -1003,10 +1003,10 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Serializes the XML node to a JSON string using formatting.
+        /// Serializes the <see cref="XmlNode"/> to a JSON string using formatting.
         /// </summary>
         /// <param name="node">The node to serialize.</param>
-        /// <param name="formatting">Indicates how the output is formatted.</param>
+        /// <param name="formatting">Indicates how the output should be formatted.</param>
         /// <returns>A JSON string of the XmlNode.</returns>
         public static string SerializeXmlNode(XmlNode node, Formatting formatting)
         {
@@ -1016,10 +1016,10 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Serializes the XML node to a JSON string using formatting and omits the root object if <paramref name="omitRootObject"/> is <c>true</c>.
+        /// Serializes the <see cref="XmlNode"/> to a JSON string using formatting and omits the root object if <paramref name="omitRootObject"/> is <c>true</c>.
         /// </summary>
         /// <param name="node">The node to serialize.</param>
-        /// <param name="formatting">Indicates how the output is formatted.</param>
+        /// <param name="formatting">Indicates how the output should be formatted.</param>
         /// <param name="omitRootObject">Omits writing the root object.</param>
         /// <returns>A JSON string of the XmlNode.</returns>
         public static string SerializeXmlNode(XmlNode node, Formatting formatting, bool omitRootObject)
@@ -1030,7 +1030,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Deserializes the XmlNode from a JSON string.
+        /// Deserializes the <see cref="XmlNode"/> from a JSON string.
         /// </summary>
         /// <param name="value">The JSON string.</param>
         /// <returns>The deserialized XmlNode</returns>
@@ -1040,7 +1040,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Deserializes the XmlNode from a JSON string nested in a root elment specified by <paramref name="deserializeRootElementName"/>.
+        /// Deserializes the <see cref="XmlNode"/> from a JSON string nested in a root element specified by <paramref name="deserializeRootElementName"/>.
         /// </summary>
         /// <param name="value">The JSON string.</param>
         /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>
@@ -1051,8 +1051,8 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Deserializes the XmlNode from a JSON string nested in a root elment specified by <paramref name="deserializeRootElementName"/>
-        /// and writes a .NET array attribute for collections.
+        /// Deserializes the <see cref="XmlNode"/> from a JSON string nested in a root element specified by <paramref name="deserializeRootElementName"/>
+        /// and writes a Json.NET array attribute for collections.
         /// </summary>
         /// <param name="value">The JSON string.</param>
         /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>
@@ -1086,7 +1086,7 @@ namespace Newtonsoft.Json
         /// Serializes the <see cref="XNode"/> to a JSON string using formatting.
         /// </summary>
         /// <param name="node">The node to convert to JSON.</param>
-        /// <param name="formatting">Indicates how the output is formatted.</param>
+        /// <param name="formatting">Indicates how the output should be formatted.</param>
         /// <returns>A JSON string of the XNode.</returns>
         public static string SerializeXNode(XObject node, Formatting formatting)
         {
@@ -1097,7 +1097,7 @@ namespace Newtonsoft.Json
         /// Serializes the <see cref="XNode"/> to a JSON string using formatting and omits the root object if <paramref name="omitRootObject"/> is <c>true</c>.
         /// </summary>
         /// <param name="node">The node to serialize.</param>
-        /// <param name="formatting">Indicates how the output is formatted.</param>
+        /// <param name="formatting">Indicates how the output should be formatted.</param>
         /// <param name="omitRootObject">Omits writing the root object.</param>
         /// <returns>A JSON string of the XNode.</returns>
         public static string SerializeXNode(XObject node, Formatting formatting, bool omitRootObject)
@@ -1118,7 +1118,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Deserializes the <see cref="XNode"/> from a JSON string nested in a root elment specified by <paramref name="deserializeRootElementName"/>.
+        /// Deserializes the <see cref="XNode"/> from a JSON string nested in a root element specified by <paramref name="deserializeRootElementName"/>.
         /// </summary>
         /// <param name="value">The JSON string.</param>
         /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>
@@ -1129,8 +1129,8 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Deserializes the <see cref="XNode"/> from a JSON string nested in a root elment specified by <paramref name="deserializeRootElementName"/>
-        /// and writes a .NET array attribute for collections.
+        /// Deserializes the <see cref="XNode"/> from a JSON string nested in a root element specified by <paramref name="deserializeRootElementName"/>
+        /// and writes a Json.NET array attribute for collections.
         /// </summary>
         /// <param name="value">The JSON string.</param>
         /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>

Src/Newtonsoft.Json/JsonConverter.cs

@@ -65,7 +65,7 @@ namespace Newtonsoft.Json
 
         /// <summary>
         /// <para>
-        /// Gets the <see cref="JsonSchema"/> of the JSON produced by the JsonConverter.
+        /// Gets the <see cref="JsonSchema"/> of the JSON produced by the <see cref="JsonConverter"/>.
         /// </para>
         /// <note type="caution">
         /// JSON Schema validation has been moved to its own package. See <see href="http://www.newtonsoft.com/jsonschema">http://www.newtonsoft.com/jsonschema</see> for more details.

Src/Newtonsoft.Json/JsonConverterAttribute.cs

@@ -47,7 +47,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by ConverterType.  
+        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by <see cref="ConverterType"/>.
         /// If null, the default constructor is used.
         /// </summary>
         public object[] ConverterParameters { get; private set; }

Src/Newtonsoft.Json/JsonPropertyAttribute.cs

@@ -55,13 +55,15 @@ namespace Newtonsoft.Json
         public Type ItemConverterType { get; set; }
 
         /// <summary>
-        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by ItemConverterType.
+        /// The parameter list to use when constructing the <see cref="JsonConverter"/> described by <see cref="ItemConverterType"/>.
         /// If null, the default constructor is used.
         /// When non-null, there must be a constructor defined in the <see cref="JsonConverter"/> that exactly matches the number,
         /// order, and type of these parameters.
         /// </summary>
         /// <example>
+        /// <code>
         /// [JsonProperty(ItemConverterType = typeof(MyContainerConverter), ItemConverterParameters = new object[] { 123, "Four" })]
+        /// </code>
         /// </example>
         public object[] ItemConverterParameters { get; set; }
 
@@ -78,7 +80,9 @@ namespace Newtonsoft.Json
         /// order, and type of these parameters.
         /// </summary>
         /// <example>
+        /// <code>
         /// [JsonProperty(NamingStrategyType = typeof(MyNamingStrategy), NamingStrategyParameters = new object[] { 123, "Four" })]
+        /// </code>
         /// </example>
         public object[] NamingStrategyParameters { get; set; }
 

Src/Newtonsoft.Json/JsonReader.cs

@@ -51,7 +51,7 @@ namespace Newtonsoft.Json
         protected internal enum State
         {
             /// <summary>
-            /// The Read method has not been called.
+            /// The <see cref="Read"/> method has not been called.
             /// </summary>
             Start,
 
@@ -86,7 +86,7 @@ namespace Newtonsoft.Json
             Array,
 
             /// <summary>
-            /// The Close method has been called.
+            /// The <see cref="Close"/> method has been called.
             /// </summary>
             Closed,
 
@@ -101,7 +101,7 @@ namespace Newtonsoft.Json
             ConstructorStart,
 
             /// <summary>
-            /// Reader in a constructor.
+            /// Reader is in a constructor.
             /// </summary>
             Constructor,
 
@@ -145,8 +145,8 @@ namespace Newtonsoft.Json
         /// <see cref="TextReader"/> should be closed when the reader is closed.
         /// </summary>
         /// <value>
-        /// true to close the underlying stream or <see cref="TextReader"/> when
-        /// the reader is closed; otherwise false. The default is true.
+        /// <c>true</c> to close the underlying stream or <see cref="TextReader"/> when
+        /// the reader is closed; otherwise <c>false</c>. The default is <c>true</c>.
         /// </value>
         public bool CloseInput { get; set; }
 
@@ -155,7 +155,8 @@ namespace Newtonsoft.Json
         /// be read from a continuous stream without erroring.
         /// </summary>
         /// <value>
-        /// true to support reading multiple pieces of JSON content; otherwise false. The default is false.
+        /// <c>true</c> to support reading multiple pieces of JSON content; otherwise <c>false</c>.
+        /// The default is <c>false</c>.
         /// </value>
         public bool SupportMultipleContent { get; set; }
 
@@ -169,7 +170,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> time zones are handling when reading JSON.
+        /// Gets or sets how <see cref="DateTime"/> time zones are handled when reading JSON.
         /// </summary>
         public DateTimeZoneHandling DateTimeZoneHandling
         {
@@ -186,7 +187,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
+        /// Gets or sets how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
         /// </summary>
         public DateParseHandling DateParseHandling
         {
@@ -209,7 +210,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
+        /// Gets or sets how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
         /// </summary>
         public FloatParseHandling FloatParseHandling
         {
@@ -226,7 +227,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how custom date formatted strings are parsed when reading JSON.
+        /// Gets or sets how custom date formatted strings are parsed when reading JSON.
         /// </summary>
         public string DateFormatString
         {
@@ -268,7 +269,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Gets The Common Language Runtime (CLR) type for the current JSON token.
+        /// Gets the .NET type for the current JSON token.
         /// </summary>
         public virtual Type ValueType
         {
@@ -337,7 +338,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="JsonReader"/> class with the specified <see cref="TextReader"/>.
+        /// Initializes a new instance of the <see cref="JsonReader"/> class.
         /// </summary>
         protected JsonReader()
         {
@@ -1113,7 +1114,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Releases unmanaged and - optionally - managed resources
+        /// Releases unmanaged and - optionally - managed resources.
         /// </summary>
         /// <param name="disposing"><c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.</param>
         protected virtual void Dispose(bool disposing)

Src/Newtonsoft.Json/JsonRequiredAttribute.cs

@@ -30,7 +30,7 @@ using System.Text;
 namespace Newtonsoft.Json
 {
     /// <summary>
-    /// Instructs the <see cref="JsonSerializer"/> to always serialize the member, and require the member has a value.
+    /// Instructs the <see cref="JsonSerializer"/> to always serialize the member, and to require that the member has a value.
     /// </summary>
     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false)]
     public sealed class JsonRequiredAttribute : Attribute

Src/Newtonsoft.Json/JsonSerializer.cs

@@ -244,7 +244,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how reference loops (e.g. a class referencing itself) is handled.
+        /// Gets or sets how reference loops (e.g. a class referencing itself) is handled.
         /// </summary>
         public virtual ReferenceLoopHandling ReferenceLoopHandling
         {
@@ -261,7 +261,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how missing members (e.g. JSON contains a property that isn't a member on the object) are handled during deserialization.
+        /// Gets or sets how missing members (e.g. JSON contains a property that isn't a member on the object) are handled during deserialization.
         /// </summary>
         public virtual MissingMemberHandling MissingMemberHandling
         {
@@ -278,7 +278,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how null values are handled during serialization and deserialization.
+        /// Gets or sets how null values are handled during serialization and deserialization.
         /// </summary>
         public virtual NullValueHandling NullValueHandling
         {
@@ -295,7 +295,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how null default are handled during serialization and deserialization.
+        /// Gets or sets how default values are handled during serialization and deserialization.
         /// </summary>
         public virtual DefaultValueHandling DefaultValueHandling
         {
@@ -412,7 +412,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how dates are written to JSON text.
+        /// Gets or sets how dates are written to JSON text.
         /// </summary>
         public virtual DateFormatHandling DateFormatHandling
         {
@@ -421,7 +421,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> time zones are handling during serialization and deserialization.
+        /// Gets or sets how <see cref="DateTime"/> time zones are handled during serialization and deserialization.
         /// </summary>
         public virtual DateTimeZoneHandling DateTimeZoneHandling
         {
@@ -430,7 +430,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
+        /// Gets or sets how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
         /// </summary>
         public virtual DateParseHandling DateParseHandling
         {
@@ -439,7 +439,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
+        /// Gets or sets how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
         /// </summary>
         public virtual FloatParseHandling FloatParseHandling
         {
@@ -448,7 +448,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
+        /// Gets or sets how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
         /// <see cref="F:System.Double.PositiveInfinity"/> and <see cref="F:System.Double.NegativeInfinity"/>,
         /// are written as JSON text.
         /// </summary>
@@ -459,7 +459,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how strings are escaped when writing JSON text.
+        /// Gets or sets how strings are escaped when writing JSON text.
         /// </summary>
         public virtual StringEscapeHandling StringEscapeHandling
         {
@@ -468,7 +468,8 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatted when writing JSON text, and the expected date format when reading JSON text.
+        /// Gets or sets how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatted when writing JSON text,
+        /// and the expected date format when reading JSON text.
         /// </summary>
         public virtual string DateFormatString
         {

Src/Newtonsoft.Json/JsonSerializerSettings.cs

@@ -128,7 +128,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Gets or sets how null default are handled during serialization and deserialization.
+        /// Gets or sets how default values are handled during serialization and deserialization.
         /// </summary>
         /// <value>The default value handling.</value>
         public DefaultValueHandling DefaultValueHandling
@@ -306,7 +306,8 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatted when writing JSON text, and the expected date format when reading JSON text.
+        /// Gets or sets how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatted when writing JSON text,
+        /// and the expected date format when reading JSON text.
         /// </summary>
         public string DateFormatString
         {
@@ -346,7 +347,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how dates are written to JSON text.
+        /// Gets or sets how dates are written to JSON text.
         /// </summary>
         public DateFormatHandling DateFormatHandling
         {
@@ -355,7 +356,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> time zones are handling during serialization and deserialization.
+        /// Gets or sets how <see cref="DateTime"/> time zones are handled during serialization and deserialization.
         /// </summary>
         public DateTimeZoneHandling DateTimeZoneHandling
         {
@@ -364,7 +365,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
+        /// Gets or sets how date formatted strings, e.g. "\/Date(1198908717056)\/" and "2012-03-21T05:40Z", are parsed when reading JSON.
         /// </summary>
         public DateParseHandling DateParseHandling
         {
@@ -373,7 +374,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
+        /// Gets or sets how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
         /// <see cref="F:System.Double.PositiveInfinity"/> and <see cref="F:System.Double.NegativeInfinity"/>,
         /// are written as JSON.
         /// </summary>
@@ -384,7 +385,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
+        /// Gets or sets how floating point numbers, e.g. 1.0 and 9.9, are parsed when reading JSON text.
         /// </summary>
         public FloatParseHandling FloatParseHandling
         {
@@ -393,7 +394,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how strings are escaped when writing JSON text.
+        /// Gets or sets how strings are escaped when writing JSON text.
         /// </summary>
         public StringEscapeHandling StringEscapeHandling
         {

Src/Newtonsoft.Json/JsonTextReader.cs

@@ -73,7 +73,7 @@ namespace Newtonsoft.Json
         internal PropertyNameTable NameTable;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="JsonReader"/> class with the specified <see cref="TextReader"/>.
+        /// Initializes a new instance of the <see cref="JsonTextReader"/> class with the specified <see cref="TextReader"/>.
         /// </summary>
         /// <param name="reader">The <c>TextReader</c> containing the XML data to read.</param>
         public JsonTextReader(TextReader reader)
@@ -2401,7 +2401,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Changes the state to closed. 
+        /// Changes the state to Closed.
         /// </summary>
         public override void Close()
         {

Src/Newtonsoft.Json/JsonTextWriter.cs

@@ -143,7 +143,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Creates an instance of the <c>JsonWriter</c> class using the specified <see cref="TextWriter"/>. 
+        /// Creates an instance of the <c>JsonTextWriter</c> class using the specified <see cref="TextWriter"/>. 
         /// </summary>
         /// <param name="textWriter">The <c>TextWriter</c> to write to.</param>
         public JsonTextWriter(TextWriter textWriter)
@@ -730,7 +730,7 @@ namespace Newtonsoft.Json
         #endregion
 
         /// <summary>
-        /// Writes out a comment <code>/*...*/</code> containing the specified text. 
+        /// Writes a comment <c>/*...*/</c> containing the specified text. 
         /// </summary>
         /// <param name="text">Text to place inside the comment.</param>
         public override void WriteComment(string text)
@@ -743,7 +743,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Writes out the given white space.
+        /// Writes the given white space.
         /// </summary>
         /// <param name="ws">The string of white space characters.</param>
         public override void WriteWhitespace(string ws)

Src/Newtonsoft.Json/JsonValidatingReader.cs

@@ -163,7 +163,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Gets the Common Language Runtime (CLR) type for the current JSON token.
+        /// Gets the .NET type for the current JSON token.
         /// </summary>
         /// <value></value>
         public override Type ValueType

Src/Newtonsoft.Json/JsonWriter.cs

@@ -123,8 +123,8 @@ namespace Newtonsoft.Json
         /// <see cref="TextReader"/> should be closed when the writer is closed.
         /// </summary>
         /// <value>
-        /// true to close the underlying stream or <see cref="TextReader"/> when
-        /// the writer is closed; otherwise false. The default is true.
+        /// <c>true</c> to close the underlying stream or <see cref="TextReader"/> when
+        /// the writer is closed; otherwise <c>false</c>. The default is <c>true</c>.
         /// </value>
         public bool CloseOutput { get; set; }
 
@@ -221,7 +221,7 @@ namespace Newtonsoft.Json
         private CultureInfo _culture;
 
         /// <summary>
-        /// Indicates how JSON text output is formatted.
+        /// Gets or sets a value indicating how JSON text output should be formatted.
         /// </summary>
         public Formatting Formatting
         {
@@ -238,7 +238,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how dates are written to JSON text.
+        /// Gets or sets how dates are written to JSON text.
         /// </summary>
         public DateFormatHandling DateFormatHandling
         {
@@ -255,7 +255,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> time zones are handling when writing JSON text.
+        /// Gets or sets how <see cref="DateTime"/> time zones are handled when writing JSON text.
         /// </summary>
         public DateTimeZoneHandling DateTimeZoneHandling
         {
@@ -272,7 +272,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how strings are escaped when writing JSON text.
+        /// Gets or sets how strings are escaped when writing JSON text.
         /// </summary>
         public StringEscapeHandling StringEscapeHandling
         {
@@ -295,7 +295,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
+        /// Gets or sets how special floating point numbers, e.g. <see cref="F:System.Double.NaN"/>,
         /// <see cref="F:System.Double.PositiveInfinity"/> and <see cref="F:System.Double.NegativeInfinity"/>,
         /// are written to JSON text.
         /// </summary>
@@ -314,7 +314,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Get or set how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatting when writing JSON text.
+        /// Gets or sets how <see cref="DateTime"/> and <see cref="DateTimeOffset"/> values are formatted when writing JSON text.
         /// </summary>
         public string DateFormatString
         {
@@ -332,7 +332,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Creates an instance of the <c>JsonWriter</c> class. 
+        /// Initializes a new instance of the <see cref="JsonWriter"/> class.
         /// </summary>
         protected JsonWriter()
         {
@@ -451,7 +451,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Writes the property name of a name/value pair on a JSON object.
+        /// Writes the property name of a name/value pair of a JSON object.
         /// </summary>
         /// <param name="name">The name of the property.</param>
         public virtual void WritePropertyName(string name)
@@ -460,7 +460,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Writes the property name of a name/value pair on a JSON object.
+        /// Writes the property name of a name/value pair of a JSON object.
         /// </summary>
         /// <param name="name">The name of the property.</param>
         /// <param name="escape">A flag to indicate whether the text should be escaped when it is written as a JSON property name.</param>
@@ -1407,7 +1407,7 @@ namespace Newtonsoft.Json
         #endregion
 
         /// <summary>
-        /// Writes out a comment <code>/*...*/</code> containing the specified text. 
+        /// Writes a comment <c>/*...*/</c> containing the specified text.
         /// </summary>
         /// <param name="text">Text to place inside the comment.</param>
         public virtual void WriteComment(string text)
@@ -1416,7 +1416,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Writes out the given white space.
+        /// Writes the given white space.
         /// </summary>
         /// <param name="ws">The string of white space characters.</param>
         public virtual void WriteWhitespace(string ws)
@@ -1431,7 +1431,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Releases unmanaged and - optionally - managed resources
+        /// Releases unmanaged and - optionally - managed resources.
         /// </summary>
         /// <param name="disposing"><c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.</param>
         protected virtual void Dispose(bool disposing)
@@ -1607,7 +1607,7 @@ namespace Newtonsoft.Json
         }
 
         /// <summary>
-        /// Sets the state of the JsonWriter,
+        /// Sets the state of the JsonWriter.
         /// </summary>
         /// <param name="token">The JsonToken being written.</param>
         /// <param name="value">The value being written.</param>

Src/Newtonsoft.Json/JsonWriterException.cs

@@ -31,7 +31,7 @@ using System.Text;
 namespace Newtonsoft.Json
 {
     /// <summary>
-    /// The exception thrown when an error occurs while reading JSON text.
+    /// The exception thrown when an error occurs while writing JSON text.
     /// </summary>
 #if !(DOTNET || PORTABLE40 || PORTABLE)
     [Serializable]

Src/Newtonsoft.Json/Linq/JTokenWriter.cs

@@ -263,7 +263,7 @@ namespace Newtonsoft.Json.Linq
         }
 
         /// <summary>
-        /// Writes out a comment <code>/*...*/</code> containing the specified text.
+        /// Writes a comment <c>/*...*/</c> containing the specified text.
         /// </summary>
         /// <param name="text">Text to place inside the comment.</param>
         public override void WriteComment(string text)

Src/Newtonsoft.Json/PreserveReferencesHandling.cs

@@ -31,7 +31,7 @@ namespace Newtonsoft.Json
 {
     /// <summary>
     /// Specifies reference handling options for the <see cref="JsonSerializer"/>.
-    /// Note that references cannot be preserved when a value is set via a non-default constructor such as types that implement ISerializable.
+    /// Note that references cannot be preserved when a value is set via a non-default constructor such as types that implement <c>ISerializable</c>.
     /// </summary>
     /// <example>
     ///   <code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="PreservingObjectReferencesOn" title="Preserve Object References" />       

Src/Newtonsoft.Json/Serialization/DefaultContractResolver.cs

@@ -92,7 +92,7 @@ namespace Newtonsoft.Json.Serialization
     }
 
     /// <summary>
-    /// Used by <see cref="JsonSerializer"/> to resolves a <see cref="JsonContract"/> for a given <see cref="System.Type"/>.
+    /// Used by <see cref="JsonSerializer"/> to resolve a <see cref="JsonContract"/> for a given <see cref="System.Type"/>.
     /// </summary>
     public class DefaultContractResolver : IContractResolver
     {

Src/Newtonsoft.Json/TypeNameAssemblyFormatHandling.cs

@@ -31,7 +31,7 @@ namespace Newtonsoft.Json
     public enum TypeNameAssemblyFormatHandling
     {
         /// <summary>
-        /// In simple mode, the assembly used during deserialization need not match exactly the assembly used during serialization. Specifically, the version numbers need not match as the LoadWithPartialName method is used to load the assembly.
+        /// In simple mode, the assembly used during deserialization need not match exactly the assembly used during serialization. Specifically, the version numbers need not match as the <c>LoadWithPartialName</c> method is used to load the assembly.
         /// </summary>
         Simple = 0,
 

Src/Newtonsoft.Json/WriteState.cs

@@ -35,7 +35,7 @@ namespace Newtonsoft.Json
         /// <summary>
         /// An exception has been thrown, which has left the <see cref="JsonWriter"/> in an invalid state.
         /// You may call the <see cref="JsonWriter.Close"/> method to put the <see cref="JsonWriter"/> in the <c>Closed</c> state.
-        /// Any other <see cref="JsonWriter"/> method calls results in an <see cref="InvalidOperationException"/> being thrown. 
+        /// Any other <see cref="JsonWriter"/> method calls result in an <see cref="InvalidOperationException"/> being thrown.
         /// </summary>
         Error = 0,