-XML comments for everything!!!

-Some members changed to internal

Src/Newtonsoft.Json.Tests/JsonSerializerTest.cs

@@ -191,6 +191,19 @@ namespace Newtonsoft.Json.Tests
     }
   }
 
+  [JsonObject(MemberSerialization.OptIn)]
+  public class Person
+  {
+    [JsonProperty]
+    public string Name { get; set; }
+
+    [JsonProperty]
+    public DateTime BirthDate { get; set; }
+
+    // not serialized
+    public string Department { get; set; }
+  }
+
   public class JsonSerializerTest : TestFixtureBase
   {
     [Test]

Src/Newtonsoft.Json.Tests/Linq/JTokenTests.cs

@@ -167,8 +167,7 @@ namespace Newtonsoft.Json.Tests.Linq
       Assert.AreEqual(true, (bool)new JValue(true));
       Assert.AreEqual(true, (bool?)new JValue(true));
       Assert.AreEqual(null, (bool?)((JValue)null));
-      Assert.AreEqual(null, (bool?)JValue.Null);
-      Assert.AreEqual(null, (bool?)JValue.Undefined);
+      Assert.AreEqual(null, (bool?)new JValue((object)null));
       Assert.AreEqual(10, (long)new JValue(10));
       Assert.AreEqual(null, (long?)new JValue((long?)null));
       Assert.AreEqual(null, (long?)(JValue)null);

Src/Newtonsoft.Json/Converters/HtmlColorConverter.cs

@@ -30,18 +30,39 @@ using System.Drawing;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts a <see cref="Color"/> object to and from JSON.
+  /// </summary>
   public class HtmlColorConverter : JsonConverter
   {
+    /// <summary>
+    /// Writes the JSON representation of the object.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> to write to.</param>
+    /// <param name="value">The value.</param>
     public override void WriteJson(JsonWriter writer, object value)
     {
       writer.WriteValue(ColorTranslator.ToHtml((Color)value));
     }
 
+    /// <summary>
+    /// Determines whether this instance can convert the specified value type.
+    /// </summary>
+    /// <param name="valueType">Type of the value.</param>
+    /// <returns>
+    /// 	<c>true</c> if this instance can convert the specified value type; otherwise, <c>false</c>.
+    /// </returns>
     public override bool CanConvert(Type valueType)
     {
       return typeof(Color).IsAssignableFrom(valueType);
     }
 
+    /// <summary>
+    /// Reads the JSON representation of the object.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType)
     {
       throw new NotImplementedException();

Src/Newtonsoft.Json/Converters/IsoDateTimeConverter.cs

@@ -7,18 +7,30 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts text in the ISO 8601 date format to and from JSON.
+  /// </summary>
   public class IsoDateTimeConverter : JsonConverter
   {
     private const string DateTimeFormat = "yyyy'-'MM'-'dd'T'HH':'mm':'ss.fffffffK";
 
     private DateTimeStyles _dateTimeStyles = DateTimeStyles.RoundtripKind;
 
+    /// <summary>
+    /// Gets or sets the date time styles used when converting a date to and from JSON.
+    /// </summary>
+    /// <value>The date time styles used when converting a date to and from JSON.</value>
     public DateTimeStyles DateTimeStyles
     {
       get { return _dateTimeStyles; }
       set { _dateTimeStyles = value; }
     }
 
+    /// <summary>
+    /// Writes the JSON representation of the object.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> to write to.</param>
+    /// <param name="value">The value.</param>
     public override void WriteJson(JsonWriter writer, object value)
     {
       string text;
@@ -46,6 +58,12 @@ namespace Newtonsoft.Json.Converters
       writer.WriteValue(text);
     }
 
+    /// <summary>
+    /// Reads the JSON representation of the object.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType)
     {
       if (reader.TokenType != JsonToken.String)
@@ -59,6 +77,13 @@ namespace Newtonsoft.Json.Converters
       return DateTime.Parse(dateText, CultureInfo.InvariantCulture, _dateTimeStyles);
     }
 
+    /// <summary>
+    /// Determines whether this instance can convert the specified object type.
+    /// </summary>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>
+    /// 	<c>true</c> if this instance can convert the specified object type; otherwise, <c>false</c>.
+    /// </returns>
     public override bool CanConvert(Type objectType)
     {
       return (typeof(DateTime).IsAssignableFrom(objectType)

Src/Newtonsoft.Json/Converters/JavaScriptDateTimeConverter.cs

@@ -7,8 +7,16 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts a <see cref="DateTime"/> to and from a JavaScript date constructor (e.g. new Date(52231943)).
+  /// </summary>
   public class JavaScriptDateTimeConverter : JsonConverter
   {
+    /// <summary>
+    /// Writes the JSON representation of the object.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> to write to.</param>
+    /// <param name="value">The value.</param>
     public override void WriteJson(JsonWriter writer, object value)
     {
       long ticks;
@@ -31,6 +39,12 @@ namespace Newtonsoft.Json.Converters
       writer.WriteEndConstructor();
     }
 
+    /// <summary>
+    /// Reads the JSON representation of the object.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType)
     {
       if (reader.TokenType != JsonToken.StartConstructor || string.Compare(reader.Value.ToString(), "Date", StringComparison.Ordinal) != 0)
@@ -56,6 +70,13 @@ namespace Newtonsoft.Json.Converters
       return d;
     }
 
+    /// <summary>
+    /// Determines whether this instance can convert the specified object type.
+    /// </summary>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>
+    /// 	<c>true</c> if this instance can convert the specified object type; otherwise, <c>false</c>.
+    /// </returns>
     public override bool CanConvert(Type objectType)
     {
       return (typeof(DateTime).IsAssignableFrom(objectType)

Src/Newtonsoft.Json/Converters/JsonDateTimeSerializationMode.cs

@@ -5,11 +5,26 @@ using System.Text;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Specifies whether a DateTime object represents a local time, a Coordinated Universal Time (UTC), or is not specified as either local time or UTC.
+  /// </summary>
   public enum JsonDateTimeSerializationMode
   {
+    /// <summary>
+    /// The time represented is local time.
+    /// </summary>
     Local,
+    /// <summary>
+    /// The time represented is UTC.
+    /// </summary>
     Utc,
+    /// <summary>
+    /// The time represented is not specified as either local time or Coordinated Universal Time (UTC).
+    /// </summary>
     Unspecified,
+    /// <summary>
+    /// Preserves the DateTimeKind field of a date when a DateTime object is converted to a string and the string is then converted back to a DateTime object.
+    /// </summary>
     RoundtripKind
   }
 }

Src/Newtonsoft.Json/Converters/XmlNodeConverter.cs

@@ -33,6 +33,9 @@ using System.Linq;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts an XmlNode to and from JSON.
+  /// </summary>
   public class XmlNodeConverter : JsonConverter
   {
     private const string TextName = "#text";
@@ -44,6 +47,11 @@ namespace Newtonsoft.Json.Converters
     private const string JsonNamespaceUri = "http://james.newtonking.com/projects/json";
 
     #region Writing
+    /// <summary>
+    /// Writes the JSON representation of the object.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> to write to.</param>
+    /// <param name="value">The value.</param>
     public override void WriteJson(JsonWriter writer, object value)
     {
       XmlNode node = value as XmlNode;
@@ -245,6 +253,12 @@ namespace Newtonsoft.Json.Converters
     #endregion
 
     #region Reading
+    /// <summary>
+    /// Reads the JSON representation of the object.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType)
     {
       // maybe have CanReader and a CanWrite methods so this sort of test wouldn't be necessary
@@ -525,6 +539,13 @@ namespace Newtonsoft.Json.Converters
     }
     #endregion
 
+    /// <summary>
+    /// Determines whether this instance can convert the specified value type.
+    /// </summary>
+    /// <param name="valueType">Type of the value.</param>
+    /// <returns>
+    /// 	<c>true</c> if this instance can convert the specified value type; otherwise, <c>false</c>.
+    /// </returns>
     public override bool CanConvert(Type valueType)
     {
       return typeof(XmlNode).IsAssignableFrom(valueType);

Src/Newtonsoft.Json/Identifier.cs

@@ -37,15 +37,26 @@ using System.ComponentModel;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// 
+  /// </summary>
   public class Identifier
   {
     private string _name;
 
+    /// <summary>
+    /// Gets the name.
+    /// </summary>
+    /// <value>The name.</value>
     public string Name
     {
       get { return _name; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Identifier"/> class.
+    /// </summary>
+    /// <param name="name">The name.</param>
     public Identifier(string name)
     {
       _name = name;
@@ -56,6 +67,14 @@ namespace Newtonsoft.Json
       return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z');
     }
 
+    /// <summary>
+    /// Determines whether the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>.
+    /// </summary>
+    /// <param name="obj">The <see cref="T:System.Object"/> to compare with the current <see cref="T:System.Object"/>.</param>
+    /// <returns>
+    /// true if the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>; otherwise, false.
+    /// </returns>
+    /// <exception cref="T:System.NullReferenceException">The <paramref name="obj"/> parameter is null.</exception>
     public override bool Equals(object obj)
     {
       Identifier function = obj as Identifier;
@@ -63,11 +82,22 @@ namespace Newtonsoft.Json
       return Equals(function);
     }
 
+    /// <summary>
+    /// Equalses the specified function.
+    /// </summary>
+    /// <param name="function">The function.</param>
+    /// <returns></returns>
     public bool Equals(Identifier function)
     {
       return (_name == function.Name);
     }
 
+    /// <summary>
+    /// Equalses the specified a.
+    /// </summary>
+    /// <param name="a">A.</param>
+    /// <param name="b">The b.</param>
+    /// <returns></returns>
     public static bool Equals(Identifier a, Identifier b)
     {
       if (a == b)
@@ -79,21 +109,45 @@ namespace Newtonsoft.Json
       return false;
     }
 
+    /// <summary>
+    /// Serves as a hash function for a particular type.
+    /// </summary>
+    /// <returns>
+    /// A hash code for the current <see cref="T:System.Object"/>.
+    /// </returns>
     public override int GetHashCode()
     {
       return _name.GetHashCode();
     }
 
+    /// <summary>
+    /// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
+    /// </summary>
+    /// <returns>
+    /// A <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
+    /// </returns>
     public override string ToString()
     {
       return _name;
     }
 
+    /// <summary>
+    /// Implements the operator ==.
+    /// </summary>
+    /// <param name="a">A.</param>
+    /// <param name="b">The b.</param>
+    /// <returns>The result of the operator.</returns>
     public static bool operator ==(Identifier a, Identifier b)
     {
       return Identifier.Equals(a, b);
     }
 
+    /// <summary>
+    /// Implements the operator !=.
+    /// </summary>
+    /// <param name="a">A.</param>
+    /// <param name="b">The b.</param>
+    /// <returns>The result of the operator.</returns>
     public static bool operator !=(Identifier a, Identifier b)
     {
       return !Identifier.Equals(a, b);

Src/Newtonsoft.Json/JavaScriptConvert.cs

@@ -117,7 +117,7 @@ namespace Newtonsoft.Json
       return ToStringInternal(value, DateTimeKind.Local);
     }
 
-    public static string ToStringInternal(DateTimeOffset value, DateTimeKind kind)
+    internal static string ToStringInternal(DateTimeOffset value, DateTimeKind kind)
     {
       long javaScriptTicks = ConvertDateTimeToJavaScriptTicks(value);
 
@@ -388,15 +388,21 @@ namespace Newtonsoft.Json
     }
 
     /// <summary>
-    /// Serializes the specified object to a Json object.
+    /// Serializes the specified object to a JSON string.
     /// </summary>
     /// <param name="value">The object to serialize.</param>
-    /// <returns>A Json string representation of the object.</returns>
+    /// <returns>A JSON string representation of the object.</returns>
     public static string SerializeObject(object value)
     {
       return SerializeObject(value, null);
     }
 
+    /// <summary>
+    /// Serializes the specified object to a JSON string using a collection of <see cref="JsonConverter"/>.
+    /// </summary>
+    /// <param name="value">The object to serialize.</param>
+    /// <param name="converters">A collection converters used while serializing.</param>
+    /// <returns>A JSON string representation of the object.</returns>
     public static string SerializeObject(object value, params JsonConverter[] converters)
     {
       StringWriter sw = new StringWriter(CultureInfo.InvariantCulture);
@@ -468,7 +474,7 @@ namespace Newtonsoft.Json
     }
 
     /// <summary>
-    /// Deserializes the specified object to a Json object.
+    /// Deserializes the JSON string to the specified type.
     /// </summary>
     /// <typeparam name="T">The type of the object to deserialize.</typeparam>
     /// <param name="value">The object to deserialize.</param>
@@ -479,6 +485,13 @@ namespace Newtonsoft.Json
       return (T)DeserializeObject(value, typeof(T), converters);
     }
 
+    /// <summary>
+    /// Deserializes the JSON string to the specified type.
+    /// </summary>
+    /// <param name="value">The object to deserialize.</param>
+    /// <param name="type">The type of the object to deserialize.</param>
+    /// <param name="converters">Converters to use while deserializing.</param>
+    /// <returns>The deserialized object from the JSON string.</returns>
     public static object DeserializeObject(string value, Type type, params JsonConverter[] converters)
     {
       StringReader sr = new StringReader(value);
@@ -502,6 +515,11 @@ namespace Newtonsoft.Json
       return deserializedValue;
     }
 
+    /// <summary>
+    /// Serializes the XML node to a JSON string.
+    /// </summary>
+    /// <param name="node">The node to serialize.</param>
+    /// <returns>A JSON string of the XmlNode.</returns>
     public static string SerializeXmlNode(XmlNode node)
     {
       XmlNodeConverter converter = new XmlNodeConverter();
@@ -509,6 +527,11 @@ namespace Newtonsoft.Json
       return SerializeObject(node, converter);
     }
 
+    /// <summary>
+    /// Deserializes the XmlNode from a JSON string.
+    /// </summary>
+    /// <param name="value">The JSON string.</param>
+    /// <returns>The deserialized XmlNode</returns>
     public static XmlNode DeserializeXmlNode(string value)
     {
       XmlNodeConverter converter = new XmlNodeConverter();

Src/Newtonsoft.Json/JsonConverter.cs

@@ -30,10 +30,33 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Converts an object to and from JSON.
+  /// </summary>
   public abstract class JsonConverter
   {
+    /// <summary>
+    /// Writes the JSON representation of the object.
+    /// </summary>
+    /// <param name="writer">The <see cref="JsonWriter"/> to write to.</param>
+    /// <param name="value">The value.</param>
     public abstract void WriteJson(JsonWriter writer, object value);
+
+    /// <summary>
+    /// Reads the JSON representation of the object.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>The object value.</returns>
     public abstract object ReadJson(JsonReader reader, Type objectType);
+
+    /// <summary>
+    /// Determines whether this instance can convert the specified object type.
+    /// </summary>
+    /// <param name="objectType">Type of the object.</param>
+    /// <returns>
+    /// 	<c>true</c> if this instance can convert the specified object type; otherwise, <c>false</c>.
+    /// </returns>
     public abstract bool CanConvert(Type objectType);
   }
 }

Src/Newtonsoft.Json/JsonConverterCollection.cs

@@ -30,6 +30,9 @@ using System.Collections.ObjectModel;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Represents a collection of <see cref="JsonConverter"/>.
+  /// </summary>
   public class JsonConverterCollection : Collection<JsonConverter>
   {
   }

Src/Newtonsoft.Json/JsonIgnoreAttribute.cs

@@ -29,6 +29,9 @@ using System.Text;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Instructs the <see cref="JsonSerializer"/> not to serialize the public field or public read/write property value.
+  /// </summary>
   [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false)]
   public sealed class JsonIgnoreAttribute : Attribute
   {

Src/Newtonsoft.Json/JsonObjectAttribute.cs

@@ -30,21 +30,35 @@ using System.Text;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Instructs the <see cref="JsonSerializer"/> how to serialize the object.
+  /// </summary>
   [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface, AllowMultiple = false)]
   public sealed class JsonObjectAttribute : Attribute
   {
     private MemberSerialization _memberSerialization = MemberSerialization.OptOut;
 
+    /// <summary>
+    /// Gets or sets the member serialization.
+    /// </summary>
+    /// <value>The member serialization.</value>
     public MemberSerialization MemberSerialization
     {
       get { return _memberSerialization; }
       set { _memberSerialization = value; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonObjectAttribute"/> class.
+    /// </summary>
     public JsonObjectAttribute()
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonObjectAttribute"/> class with the specified member serialization.
+    /// </summary>
+    /// <param name="memberSerialization">The member serialization.</param>
     public JsonObjectAttribute(MemberSerialization memberSerialization)
     {
       MemberSerialization = memberSerialization;

Src/Newtonsoft.Json/JsonPropertyAttribute.cs

@@ -2,21 +2,35 @@ using System;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Instructs the <see cref="JsonSerializer"/> to always serialize the member with the specified name.
+  /// </summary>
   [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false)]
   public sealed class JsonPropertyAttribute : Attribute
   {
     private string _propertyName;
 
+    /// <summary>
+    /// Gets or sets the name of the property.
+    /// </summary>
+    /// <value>The name of the property.</value>
     public string PropertyName
     {
       get { return _propertyName; }
       set { _propertyName = value; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonPropertyAttribute"/> class.
+    /// </summary>
     public JsonPropertyAttribute()
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonPropertyAttribute"/> class with the specified name.
+    /// </summary>
+    /// <param name="propertyName">Name of the property.</param>
     public JsonPropertyAttribute(string propertyName)
     {
       _propertyName = propertyName;

Src/Newtonsoft.Json/JsonReader.cs

@@ -39,20 +39,62 @@ namespace Newtonsoft.Json
   /// </summary>
   public abstract class JsonReader : IDisposable
   {
+    /// <summary>
+    /// Specifies the state of the reader.
+    /// </summary>
     protected enum State
     {
+      /// <summary>
+      /// The Read method has not been called.
+      /// </summary>
       Start,
+      /// <summary>
+      /// The end of the file has been reached successfully.
+      /// </summary>
       Complete,
+      /// <summary>
+      /// Reader is at a property.
+      /// </summary>
       Property,
+      /// <summary>
+      /// Reader is at the start of an object.
+      /// </summary>
       ObjectStart,
+      /// <summary>
+      /// Reader is in an object.
+      /// </summary>
       Object,
+      /// <summary>
+      /// Reader is at the start of an array.
+      /// </summary>
       ArrayStart,
+      /// <summary>
+      /// Reader is in an array.
+      /// </summary>
       Array,
+      /// <summary>
+      /// The Close method has been called.
+      /// </summary>
       Closed,
+      /// <summary>
+      /// Reader has just read a value.
+      /// </summary>
       PostValue,
+      /// <summary>
+      /// Reader is at the start of a constructor.
+      /// </summary>
       ConstructorStart,
+      /// <summary>
+      /// Reader in a constructor.
+      /// </summary>
       Constructor,
+      /// <summary>
+      /// An error occurred that prevents the read operation from continuing.
+      /// </summary>
       Error,
+      /// <summary>
+      /// The end of the file has been reached successfully.
+      /// </summary>
       Finished
     }
 
@@ -63,6 +105,10 @@ namespace Newtonsoft.Json
     private char _quoteChar;
     private State _currentState;
 
+    /// <summary>
+    /// Gets the current reader state.
+    /// </summary>
+    /// <value>The current reader state.</value>
     protected State CurrentState
     {
       get { return _currentState; }
@@ -106,6 +152,10 @@ namespace Newtonsoft.Json
       get { return _valueType; }
     }
 
+    /// <summary>
+    /// Gets the depth of the current token in the JSON document.
+    /// </summary>
+    /// <value>The depth of the current token in the JSON document.</value>
     public int Depth
     {
       get
@@ -156,6 +206,9 @@ namespace Newtonsoft.Json
     /// <returns></returns>
     public abstract bool Read();
 
+    /// <summary>
+    /// Skips the children of the current token.
+    /// </summary>
     public void Skip()
     {
       if (IsStartToken(TokenType))
@@ -168,11 +221,20 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Sets the current token.
+    /// </summary>
+    /// <param name="newToken">The new token.</param>
     protected void SetToken(JsonToken newToken)
     {
       SetToken(newToken, null);
     }
 
+    /// <summary>
+    /// Sets the current token and value.
+    /// </summary>
+    /// <param name="newToken">The new token.</param>
+    /// <param name="value">The value.</param>
     protected virtual void SetToken(JsonToken newToken, object value)
     {
       _token = newToken;
@@ -242,6 +304,9 @@ namespace Newtonsoft.Json
         throw new JsonReaderException("JsonToken {0} is not valid for closing JsonType {1}.".FormatWith(CultureInfo.InvariantCulture, endToken, currentObject));
     }
 
+    /// <summary>
+    /// Sets the state based on current token type.
+    /// </summary>
     protected void SetStateBasedOnCurrent()
     {
       JsonTokenType currentObject = Peek();
@@ -315,6 +380,10 @@ namespace Newtonsoft.Json
       Dispose(true);
     }
 
+    /// <summary>
+    /// 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)
     {
       if (_currentState != State.Closed && disposing)

Src/Newtonsoft.Json/JsonSerializer.cs

@@ -97,6 +97,10 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Gets or sets how objects are created.
+    /// </summary>
+    /// <value>The object creation handling.</value>
     public ObjectCreationHandling ObjectCreationHandling
     {
       get { return _objectCreationHandling; }
@@ -109,6 +113,10 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Gets a collection <see cref="JsonConverter"/> that will be used during serialization.
+    /// </summary>
+    /// <value>Collection <see cref="JsonConverter"/> that will be used during serialization.</value>
     public JsonConverterCollection Converters
     {
       get
@@ -146,7 +154,7 @@ namespace Newtonsoft.Json
     /// Deserializes the Json structure contained by the specified <see cref="JsonReader"/>
     /// into an instance of the specified type.
     /// </summary>
-    /// <param name="reader">The type of object to create.</param>
+    /// <param name="reader">The <see cref="JsonReader"/> containing the object.</param>
     /// <param name="objectType">The <see cref="Type"/> of object being deserialized.</param>
     /// <returns>The instance of <paramref name="objectType"/> being deserialized.</returns>
     public object Deserialize(JsonReader reader, Type objectType)
@@ -163,6 +171,13 @@ namespace Newtonsoft.Json
         return CreateJToken(reader);
     }
 
+    /// <summary>
+    /// Deserializes the Json structure contained by the specified <see cref="StringReader"/>
+    /// into an instance of the specified type.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> containing the object.</param>
+    /// <param name="objectType">The <see cref="Type"/> of object being deserialized.</param>
+    /// <returns>The instance of <paramref name="objectType"/> being deserialized.</returns>
     public object Deserialize(StringReader reader, Type objectType)
     {
       return Deserialize(new JsonTextReader(reader), objectType);
@@ -351,6 +366,11 @@ namespace Newtonsoft.Json
       return memberMappings;
     }
 
+    /// <summary>
+    /// Gets the serializable members for the given <see cref="Type"/>.
+    /// </summary>
+    /// <param name="objectType">The object <see cref="Type"/> to get seralizable members for.</param>
+    /// <returns>Seralizable members for the given type.</returns>
     protected virtual List<MemberInfo> GetSerializableMembers(Type objectType)
     {
       return ReflectionUtils.GetFieldsAndProperties(objectType, BindingFlags.Public | BindingFlags.Instance);

Src/Newtonsoft.Json/JsonTextReader.cs

@@ -147,6 +147,11 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Sets the current token and value.
+    /// </summary>
+    /// <param name="newToken">The new token.</param>
+    /// <param name="value">The value.</param>
     protected override void SetToken(JsonToken newToken, object value)
     {
       base.SetToken(newToken, value);
@@ -787,7 +792,7 @@ namespace Newtonsoft.Json
     }
 
     /// <summary>
-    /// Changes the <see cref="State"/> to Closed. 
+    /// Changes the <see cref="P:State"/> to Closed. 
     /// </summary>
     public override void Close()
     {

Src/Newtonsoft.Json/JsonTextWriter.cs

@@ -145,6 +145,10 @@ namespace Newtonsoft.Json
       _writer.Write("[");
     }
 
+    /// <summary>
+    /// Writes the start of a constructor with the given name.
+    /// </summary>
+    /// <param name="name">The name of the constructor.</param>
     public override void WriteStartConstructor(string name)
     {
       base.WriteStartConstructor(name);
@@ -154,6 +158,10 @@ namespace Newtonsoft.Json
       _writer.Write("(");
     }
 
+    /// <summary>
+    /// Writes the specified end token.
+    /// </summary>
+    /// <param name="token">The end token to write.</param>
     protected override void WriteEnd(JsonToken token)
     {
       switch (token)
@@ -191,6 +199,9 @@ namespace Newtonsoft.Json
       _writer.Write(':');
     }
 
+    /// <summary>
+    /// Writes indent characters.
+    /// </summary>
     protected override void WriteIndent()
     {
       if (Formatting == Formatting.Indented)
@@ -208,11 +219,17 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Writes the JSON value delimiter.
+    /// </summary>
     protected override void WriteValueDelimiter()
     {
       _writer.Write(',');
     }
 
+    /// <summary>
+    /// Writes an indent space.
+    /// </summary>
     protected override void WriteIndentSpace()
     {
       _writer.Write(' ');

Src/Newtonsoft.Json/JsonWriter.cs

@@ -81,7 +81,7 @@ namespace Newtonsoft.Json
     /// </summary>
     None,
     /// <summary>
-    /// Causes child objects to be indented according to the <see cref="JsonWriter.Indentation"/> and <see cref="JsonWriter.IndentChar"/> settings.
+    /// Causes child objects to be indented according to the <see cref="P:JsonWriter.Indentation"/> and <see cref="P:JsonWriter.IndentChar"/> settings.
     /// </summary>
     Indented
   }
@@ -136,6 +136,10 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Gets the top.
+    /// </summary>
+    /// <value>The top.</value>
     protected int Top
     {
       get { return _top; }
@@ -183,9 +187,8 @@ 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>JsonWriter</c> class. 
     /// </summary>
-    /// <param name="textWriter">The <c>TextWriter</c> to write to.</param>
     public JsonWriter()
     {
       _stack = new List<JsonTokenType>(1);
@@ -263,12 +266,19 @@ namespace Newtonsoft.Json
       AutoCompleteClose(JsonToken.EndArray);
     }
 
+    /// <summary>
+    /// Writes the start of a constructor with the given name.
+    /// </summary>
+    /// <param name="name">The name of the constructor.</param>
     public virtual void WriteStartConstructor(string name)
     {
       AutoComplete(JsonToken.StartConstructor);
       Push(JsonTokenType.Constructor);
     }
 
+    /// <summary>
+    /// Writes the end constructor.
+    /// </summary>
     public void WriteEndConstructor()
     {
       AutoCompleteClose(JsonToken.EndConstructor);
@@ -291,6 +301,10 @@ namespace Newtonsoft.Json
       WriteEnd(Peek());
     }
 
+    /// <summary>
+    /// Writes the current <see cref="JsonReader"/> token.
+    /// </summary>
+    /// <param name="reader">The <see cref="JsonReader"/> to read the token from.</param>
     public void WriteToken(JsonReader reader)
     {
       ValidationUtils.ArgumentNotNull(reader, "reader");
@@ -473,18 +487,31 @@ namespace Newtonsoft.Json
       }
     }
 
+    /// <summary>
+    /// Writes the specified end token.
+    /// </summary>
+    /// <param name="token">The end token to write.</param>
     protected virtual void WriteEnd(JsonToken token)
     {
     }
 
+    /// <summary>
+    /// Writes indent characters.
+    /// </summary>
     protected virtual void WriteIndent()
     {
     }
 
+    /// <summary>
+    /// Writes the JSON value delimiter.
+    /// </summary>
     protected virtual void WriteValueDelimiter()
     {
     }
 
+    /// <summary>
+    /// Writes an indent space.
+    /// </summary>
     protected virtual void WriteIndentSpace()
     {
     }

Src/Newtonsoft.Json/Linq/Extensions.cs

@@ -33,8 +33,17 @@ using System.Globalization;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Contains the LINQ to JSON extension methods.
+  /// </summary>
   public static class Extensions
   {
+    /// <summary>
+    /// Returns a collection of tokens that contains the ancestors of every token in the source collection.
+    /// </summary>
+    /// <typeparam name="T">The type of the objects in source, constrained to <see cref="JToken"/>.</typeparam>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the ancestors of every node in the source collection.</returns>
     public static IEnumerable<JToken> Ancestors<T>(this IEnumerable<T> source) where T : JToken
     {
       ValidationUtils.ArgumentNotNull(source, "source");
@@ -50,6 +59,12 @@ namespace Newtonsoft.Json.Linq
     //  return source.SelectMany(j => j.AncestorsAndSelf());
     //}
 
+    /// <summary>
+    /// Returns a collection of tokens that contains the descendants of every token in the source collection.
+    /// </summary>
+    /// <typeparam name="T">The type of the objects in source, constrained to <see cref="JContainer"/>.</typeparam>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the descendants of every node in the source collection.</returns>
     public static IEnumerable<JToken> Descendants<T>(this IEnumerable<T> source) where T : JContainer
     {
       ValidationUtils.ArgumentNotNull(source, "source");
@@ -65,6 +80,11 @@ namespace Newtonsoft.Json.Linq
     //  return source.SelectMany(j => j.DescendantsAndSelf());
     //}
 
+    /// <summary>
+    /// Returns a collection of child properties of every object in the source collection.
+    /// </summary>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JObject"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JProperty"/> that contains the properties of every object in the source collection.</returns>
     public static IEnumerable<JProperty> Properties(this IEnumerable<JObject> source)
     {
       ValidationUtils.ArgumentNotNull(source, "source");
@@ -72,21 +92,45 @@ namespace Newtonsoft.Json.Linq
       return source.SelectMany(d => d.Properties());
     }
 
+    /// <summary>
+    /// Returns a collection of child values of every object in the source collection with the given key.
+    /// </summary>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <param name="key">The token key.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the values of every node in the source collection with the given key.</returns>
     public static IEnumerable<JToken> Values(this IEnumerable<JToken> source, object key)
     {
       return Values<JToken, JToken>(source, key);
     }
 
+    /// <summary>
+    /// Returns a collection of child values of every object in the source collection.
+    /// </summary>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the values of every node in the source collection.</returns>
     public static IEnumerable<JToken> Values(this IEnumerable<JToken> source)
     {
       return Values<JToken, JToken>(source, null);
     }
 
+    /// <summary>
+    /// Returns a collection of converted child values of every object in the source collection with the given key.
+    /// </summary>
+    /// <typeparam name="U">The type to convert the values to.</typeparam>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <param name="key">The token key.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> that contains the converted values of every node in the source collection with the given key.</returns>
     public static IEnumerable<U> Values<U>(this IEnumerable<JToken> source, object key)
     {
       return Values<JToken, U>(source, key);
     }
 
+    /// <summary>
+    /// Returns a collection of converted child values of every object in the source collection.
+    /// </summary>
+    /// <typeparam name="U">The type to convert the values to.</typeparam>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> that contains the converted values of every node in the source collection.</returns>
     public static IEnumerable<U> Values<U>(this IEnumerable<JToken> source)
     {
       return Values<JToken, U>(source, null);
@@ -142,11 +186,21 @@ namespace Newtonsoft.Json.Linq
     //  return source.SelectMany(c => c.Children());
     //}
 
+    /// <summary>
+    /// Returns a collection of child tokens of every array in the source collection.
+    /// </summary>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JArray"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the values of every node in the source collection.</returns>
     public static IEnumerable<JToken> Children(this IEnumerable<JArray> source)
     {
       return Children<JToken>(source);
     }
 
+    /// <summary>
+    /// Returns a collection of converted child tokens of every array in the source collection.
+    /// </summary>
+    /// <param name="source">An <see cref="IEnumerable{T}"/> of <see cref="JArray"/> that contains the source collection.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="JToken"/> that contains the converted values of every node in the source collection.</returns>
     public static IEnumerable<U> Children<U>(this IEnumerable<JArray> source)
     {
       ValidationUtils.ArgumentNotNull(source, "source");
@@ -193,10 +247,7 @@ namespace Newtonsoft.Json.Linq
       }
     }
 
-
     //TODO
     //public static void Remove<T>(this IEnumerable<T> source) where T : JContainer;
-
-
   }
 }

Src/Newtonsoft.Json/Linq/JArray.cs

@@ -33,27 +33,49 @@ using System.Globalization;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a JSON array.
+  /// </summary>
   public class JArray : JContainer
   {
+    /// <summary>
+    /// Gets the node type for this <see cref="JToken"/>.
+    /// </summary>
+    /// <value>The type.</value>
     public override JsonTokenType Type
     {
       get { return JsonTokenType.Array; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JArray"/> class.
+    /// </summary>
     public JArray()
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JArray"/> class from another <see cref="JArray"/> object.
+    /// </summary>
+    /// <param name="other">A <see cref="JArray"/> object to copy from.</param>
     public JArray(JArray other)
       : base(other)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JArray"/> class with the specified content.
+    /// </summary>
+    /// <param name="content">The contents of the array.</param>
     public JArray(params object[] content)
       : this((object)content)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JArray"/> class with the specified content.
+    /// </summary>
+    /// <param name="content">The contents of the array.</param>
     public JArray(object content)
     {
       Add(content);
@@ -70,11 +92,20 @@ namespace Newtonsoft.Json.Linq
       return new JArray(this);
     }
 
+    /// <summary>
+    /// Returns a count of this token's child tokens.
+    /// </summary>
+    /// <returns></returns>
     public int Count()
     {
       return Children().Count();
     }
 
+    /// <summary>
+    /// Loads an <see cref="JArray"/> from a <see cref="JsonReader"/>. 
+    /// </summary>
+    /// <param name="reader">A <see cref="JsonReader"/> that will be read for the content of the <see cref="JArray"/>.</param>
+    /// <returns>A <see cref="JArray"/> that contains the XML that was read from the specified <see cref="JsonReader"/>.</returns>
     public static JArray Load(JsonReader reader)
     {
       if (reader.TokenType == JsonToken.None)
@@ -98,6 +129,11 @@ namespace Newtonsoft.Json.Linq
       return a;
     }
 
+    /// <summary>
+    /// Load a <see cref="JArray"/> from a string that contains JSON.
+    /// </summary>
+    /// <param name="json">A <see cref="String"/> that contains JSON.</param>
+    /// <returns>A <see cref="JArray"/> populated from the string that contains JSON.</returns>
     public static JArray Parse(string json)
     {
       JsonReader jsonReader = new JsonTextReader(new StringReader(json));
@@ -113,6 +149,11 @@ namespace Newtonsoft.Json.Linq
         throw new ArgumentException("An item of type {0} cannot be added to content.".FormatWith(CultureInfo.InvariantCulture, o.Type));
     }
 
+    /// <summary>
+    /// Creates a <see cref="JArray"/> from an object.
+    /// </summary>
+    /// <param name="o">The object that will be used to create <see cref="JArray"/>.</param>
+    /// <returns>A <see cref="JArray"/> with the values of the specified object</returns>
     public static JArray FromObject(object o)
     {
       JToken token = FromObjectInternal(o);
@@ -123,6 +164,11 @@ namespace Newtonsoft.Json.Linq
       return (JArray)token;
     }
 
+    /// <summary>
+    /// Writes this token to a <see cref="JsonWriter"/>.
+    /// </summary>
+    /// <param name="writer">A <see cref="JsonWriter"/> into which this method will write.</param>
+    /// <param name="converters">A collection of <see cref="JsonConverter"/> which will be used when writing the token.</param>
     public override void WriteTo(JsonWriter writer, params JsonConverter[] converters)
     {
       writer.WriteStartArray();
@@ -135,6 +181,10 @@ namespace Newtonsoft.Json.Linq
       writer.WriteEndArray();
     }
 
+    /// <summary>
+    /// Gets the <see cref="JToken"/> with the specified key.
+    /// </summary>
+    /// <value>The <see cref="JToken"/> with the specified key.</value>
     public override JToken this[object key]
     {
       get

Src/Newtonsoft.Json/Linq/JConstructor.cs

@@ -32,10 +32,17 @@ using System.Globalization;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a JSON constructor.
+  /// </summary>
   public class JConstructor : JContainer
   {
     private string _name;
 
+    /// <summary>
+    /// Gets or sets the name of this constructor.
+    /// </summary>
+    /// <value>The constructor name.</value>
     public string Name
     {
       get { return _name; }
@@ -51,27 +58,48 @@ namespace Newtonsoft.Json.Linq
       get { return JsonTokenType.Constructor; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JConstructor"/> class.
+    /// </summary>
     public JConstructor()
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JConstructor"/> class from another <see cref="JConstructor"/> object.
+    /// </summary>
+    /// <param name="other">A <see cref="JConstructor"/> object to copy from.</param>
     public JConstructor(JConstructor other)
       : base(other)
     {
       _name = other.Name;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JConstructor"/> class with the specified name and content.
+    /// </summary>
+    /// <param name="name">The constructor name.</param>
+    /// <param name="content">The contents of the constructor.</param>
     public JConstructor(string name, params object[] content)
       : this(name, (object)content)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JConstructor"/> class with the specified name and content.
+    /// </summary>
+    /// <param name="name">The constructor name.</param>
+    /// <param name="content">The contents of the constructor.</param>
     public JConstructor(string name, object content)
       : this(name)
     {
       Add(content);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JConstructor"/> class with the specified name.
+    /// </summary>
+    /// <param name="name">The constructor name.</param>
     public JConstructor(string name)
     {
       _name = name;
@@ -116,6 +144,10 @@ namespace Newtonsoft.Json.Linq
       writer.WriteEndConstructor();
     }
 
+    /// <summary>
+    /// Gets the <see cref="JToken"/> with the specified key.
+    /// </summary>
+    /// <value>The <see cref="JToken"/> with the specified key.</value>
     public override JToken this[object key]
     {
       get

Src/Newtonsoft.Json/Linq/JContainer.cs

@@ -34,6 +34,9 @@ using System.Globalization;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a token that can contain other tokens.
+  /// </summary>
   public abstract class JContainer : JToken
   {
     private JToken _content;
@@ -44,15 +47,11 @@ namespace Newtonsoft.Json.Linq
       set { _content = value; }
     }
 
-    protected JContainer()
+    internal JContainer()
     {
     }
 
-    /// <summary>
-    /// Initializes a new instance of the <see cref="JContainer"/> class from another <see cref="JContainer"/> object.
-    /// </summary>
-    /// <param name="other">A <see cref="JContainer"/> object to copy from.</param>
-    protected JContainer(JContainer other)
+    internal JContainer(JContainer other)
     {
       ValidationUtils.ArgumentNotNull(other, "c");
 
@@ -105,6 +104,12 @@ namespace Newtonsoft.Json.Linq
       while (true);
     }
 
+    /// <summary>
+    /// Get the first child token of this token.
+    /// </summary>
+    /// <value>
+    /// A <see cref="JToken"/> containing the first child token of the <see cref="JToken"/>.
+    /// </value>
     public override JToken First
     {
       get
@@ -116,6 +121,12 @@ namespace Newtonsoft.Json.Linq
       }
     }
 
+    /// <summary>
+    /// Get the last child token of this token.
+    /// </summary>
+    /// <value>
+    /// A <see cref="JToken"/> containing the last child token of the <see cref="JToken"/>.
+    /// </value>
     public override JToken Last
     {
       [DebuggerStepThrough]
@@ -160,13 +171,10 @@ namespace Newtonsoft.Json.Linq
       return Children().Convert<JToken, T>();
     }
 
-    //public override T Value<T>(object key)
-    //{
-    //  JToken token = this[key];
-
-    //  return Extensions.Convert<JToken, T>(token);
-    //}
-
+    /// <summary>
+    /// Returns a collection of the descendant tokens for this token in document order.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{JToken}"/> containing the descendant tokens of the <see cref="JToken"/>.</returns>
     public IEnumerable<JToken> Descendants()
     {
       foreach (JToken o in Children())
@@ -266,17 +274,25 @@ namespace Newtonsoft.Json.Linq
         throw new Exception("Can not add {0} to {1}".FormatWith(CultureInfo.InvariantCulture, o.GetType(), GetType()));
     }
 
+    /// <summary>
+    /// Adds the specified content as children of this <see cref="JToken"/>.
+    /// </summary>
+    /// <param name="content">The content to be added.</param>
     public virtual void Add(object content)
     {
       AddInternal(true, Last, content);
     }
 
+    /// <summary>
+    /// Adds the specified content as the first children of this <see cref="JToken"/>.
+    /// </summary>
+    /// <param name="content">The content to be added.</param>
     public void AddFirst(object content)
     {
       AddInternal(false, Last, content);
     }
 
-    protected JToken CreateFromContent(object content)
+    internal JToken CreateFromContent(object content)
     {
       if (content is JToken)
         return (JToken)content;
@@ -284,17 +300,28 @@ namespace Newtonsoft.Json.Linq
         return new JValue(content);
     }
 
+    /// <summary>
+    /// Creates an <see cref="JsonWriter"/> that can be used to add tokens to the <see cref="JToken"/>.
+    /// </summary>
+    /// <returns>An <see cref="JsonWriter"/> that is ready to have content written to it.</returns>
     public JsonWriter CreateWriter()
     {
       return new JsonTokenWriter(this);
     }
 
+    /// <summary>
+    /// Replaces the children nodes of this token with the specified content.
+    /// </summary>
+    /// <param name="content">The content.</param>
     public void ReplaceAll(object content)
     {
       RemoveAll();
       Add(content);
     }
 
+    /// <summary>
+    /// Removes the child nodes from this token.
+    /// </summary>
     public void RemoveAll()
     {
       while (_content != null)
@@ -417,10 +444,10 @@ namespace Newtonsoft.Json.Linq
             parent.AddObjectSkipNotify(JValue.CreateComment(r.Value.ToString()));
             break;
           case JsonToken.Null:
-            parent.AddObjectSkipNotify(JValue.Null);
+            parent.AddObjectSkipNotify(new JValue(null, JsonTokenType.Null));
             break;
           case JsonToken.Undefined:
-            parent.AddObjectSkipNotify(JValue.Undefined);
+            parent.AddObjectSkipNotify(new JValue(null, JsonTokenType.Undefined));
             break;
           case JsonToken.PropertyName:
             JProperty property = new JProperty(r.Value.ToString());

Src/Newtonsoft.Json/Linq/JEnumerable.cs

@@ -7,12 +7,23 @@ using System.Collections;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a collection of <see cref="JToken"/> objects.
+  /// </summary>
+  /// <typeparam name="T">The type of token</typeparam>
   public struct JEnumerable<T> : IEnumerable<T> where T : JToken
   {
+    /// <summary>
+    /// An empty collection of <see cref="JToken"/> objects.
+    /// </summary>
     public static readonly JEnumerable<T> Empty = new JEnumerable<T>(Enumerable.Empty<T>());
 
     private IEnumerable<T> _enumerable;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JEnumerable{T}"/> struct.
+    /// </summary>
+    /// <param name="enumerable">The enumerable.</param>
     public JEnumerable(IEnumerable<T> enumerable)
     {
       ValidationUtils.ArgumentNotNull(enumerable, "enumerable");
@@ -20,16 +31,32 @@ namespace Newtonsoft.Json.Linq
       _enumerable = enumerable;
     }
 
+    /// <summary>
+    /// Returns an enumerator that iterates through the collection.
+    /// </summary>
+    /// <returns>
+    /// A <see cref="T:System.Collections.Generic.IEnumerator`1"/> that can be used to iterate through the collection.
+    /// </returns>
     public IEnumerator<T> GetEnumerator()
     {
       return _enumerable.GetEnumerator();
     }
 
+    /// <summary>
+    /// Returns an enumerator that iterates through a collection.
+    /// </summary>
+    /// <returns>
+    /// An <see cref="T:System.Collections.IEnumerator"/> object that can be used to iterate through the collection.
+    /// </returns>
     IEnumerator IEnumerable.GetEnumerator()
     {
       return GetEnumerator();
     }
 
+    /// <summary>
+    /// Gets the <see cref="IEnumerable{JToken}"/> with the specified key.
+    /// </summary>
+    /// <value></value>
     public IEnumerable<JToken> this[object key]
     {
       get { return Extensions.Values<T, JToken>(_enumerable, key); }

Src/Newtonsoft.Json/Linq/JObject.cs

@@ -54,11 +54,19 @@ namespace Newtonsoft.Json.Linq
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JObject"/> class with the specified content.
+    /// </summary>
+    /// <param name="content">The contents of the object.</param>
     public JObject(params object[] content)
       : this((object)content)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JObject"/> class with the specified content.
+    /// </summary>
+    /// <param name="content">The contents of the object.</param>
     public JObject(object content)
     {
       Add(content);
@@ -83,16 +91,29 @@ namespace Newtonsoft.Json.Linq
       return new JObject(this);
     }
 
+    /// <summary>
+    /// Gets the node type for this <see cref="JToken"/>.
+    /// </summary>
+    /// <value>The type.</value>
     public override JsonTokenType Type
     {
       get { return JsonTokenType.Object; }
     }
 
+    /// <summary>
+    /// Gets an <see cref="IEnumerable{JProperty}"/> of this object's properties.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{JProperty}"/> of this object's properties.</returns>
     public IEnumerable<JProperty> Properties()
     {
       return Children().Cast<JProperty>();
     }
 
+    /// <summary>
+    /// Gets a <see cref="JProperty"/> the specified name.
+    /// </summary>
+    /// <param name="name">The property name.</param>
+    /// <returns>A <see cref="JProperty"/> with the specified name or null.</returns>
     public JProperty Property(string name)
     {
       return Properties()
@@ -100,21 +121,19 @@ namespace Newtonsoft.Json.Linq
         .SingleOrDefault();
     }
 
+    /// <summary>
+    /// Gets an <see cref="JEnumerable{JToken}"/> of this object's property values.
+    /// </summary>
+    /// <returns>An <see cref="JEnumerable{JToken}"/> of this object's property values.</returns>
     public JEnumerable<JToken> PropertyValues()
     {
       return new JEnumerable<JToken>(Properties().Select(p => p.Value));
     }
 
-    //public override void Add(object content)
-    //{
-    //  ValidationUtils.ArgumentNotNull(content, "content");
-
-    //  if (!(content is JProperty) && !IsMultiContent(content))
-    //    throw new ArgumentException("Error adding {0} to JObject. JObject only supports JProperty content.".FormatWith(CultureInfo.InvariantCulture, content.GetType().Name));
-
-    //  base.Add(content);
-    //}
-
+    /// <summary>
+    /// Gets the <see cref="JToken"/> with the specified key.
+    /// </summary>
+    /// <value>The <see cref="JToken"/> with the specified key.</value>
     public override JToken this[object key]
     {
       get
@@ -131,6 +150,11 @@ namespace Newtonsoft.Json.Linq
       }
     }
 
+    /// <summary>
+    /// Loads an <see cref="JObject"/> from a <see cref="JsonReader"/>. 
+    /// </summary>
+    /// <param name="reader">A <see cref="JsonReader"/> that will be read for the content of the <see cref="JObject"/>.</param>
+    /// <returns>A <see cref="JObject"/> that contains the XML that was read from the specified <see cref="JsonReader"/>.</returns>
     public static JObject Load(JsonReader reader)
     {
       ValidationUtils.ArgumentNotNull(reader, "reader");
@@ -156,6 +180,11 @@ namespace Newtonsoft.Json.Linq
       return o;
     }
 
+    /// <summary>
+    /// Load a <see cref="JObject"/> from a string that contains JSON.
+    /// </summary>
+    /// <param name="json">A <see cref="String"/> that contains JSON.</param>
+    /// <returns>A <see cref="JObject"/> populated from the string that contains JSON.</returns>
     public static JObject Parse(string json)
     {
       JsonReader jsonReader = new JsonTextReader(new StringReader(json));
@@ -163,6 +192,11 @@ namespace Newtonsoft.Json.Linq
       return Load(jsonReader);
     }
 
+    /// <summary>
+    /// Creates a <see cref="JObject"/> from an object.
+    /// </summary>
+    /// <param name="o">The object that will be used to create <see cref="JObject"/>.</param>
+    /// <returns>A <see cref="JObject"/> with the values of the specified object</returns>
     public static JObject FromObject(object o)
     {
       JToken token = FromObjectInternal(o);
@@ -181,6 +215,11 @@ namespace Newtonsoft.Json.Linq
         throw new ArgumentException("An item of type {0} cannot be added to content.".FormatWith(CultureInfo.InvariantCulture, o.Type));
     }
 
+    /// <summary>
+    /// Writes this token to a <see cref="JsonWriter"/>.
+    /// </summary>
+    /// <param name="writer">A <see cref="JsonWriter"/> into which this method will write.</param>
+    /// <param name="converters">A collection of <see cref="JsonConverter"/> which will be used when writing the token.</param>
     public override void WriteTo(JsonWriter writer, params JsonConverter[] converters)
     {
       writer.WriteStartObject();

Src/Newtonsoft.Json/Linq/JToken.cs

@@ -140,6 +140,10 @@ namespace Newtonsoft.Json.Linq
       }
     }
 
+    internal JToken()
+    {
+    }
+
     /// <summary>
     /// Returns a collection of the ancestor tokens of this token.
     /// </summary>

Src/Newtonsoft.Json/Linq/JValue.cs

@@ -32,55 +32,87 @@ using System.Globalization;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a value in JSON (string, integer, date, etc).
+  /// </summary>
   public class JValue : JToken
   {
     private JsonTokenType _valueType;
     private object _value;
 
-    public static readonly JValue Null = new JValue(null, JsonTokenType.Null);
-    public static readonly JValue Undefined = new JValue(null, JsonTokenType.Undefined);
-
-    private JValue(object value, JsonTokenType type)
+    internal JValue(object value, JsonTokenType type)
     {
       _value = value;
       _valueType = type;
     }
 
-    public JValue(JValue value)
-      : this(value.Value, value.Type)
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class from another <see cref="JValue"/> object.
+    /// </summary>
+    /// <param name="other">A <see cref="JValue"/> object to copy from.</param>
+    public JValue(JValue other)
+      : this(other.Value, other.Type)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(long value)
       : this(value, JsonTokenType.Integer)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(ulong value)
       : this(value, JsonTokenType.Integer)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(double value)
       : this(value, JsonTokenType.Float)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(DateTime value)
       : this(value, JsonTokenType.Date)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(bool value)
       : this(value, JsonTokenType.Boolean)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(string value)
       : this(value, JsonTokenType.String)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JValue"/> class with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
     public JValue(object value)
       : this(value, GetValueType(null, value))
     {
@@ -95,12 +127,18 @@ namespace Newtonsoft.Json.Linq
       return (this == other || (_valueType == other.Type && Compare(_value, other.Value)));
     }
 
+    /// <summary>
+    /// Gets a value indicating whether this token has childen tokens.
+    /// </summary>
+    /// <value>
+    /// 	<c>true</c> if this token has child values; otherwise, <c>false</c>.
+    /// </value>
     public override bool HasValues
     {
       get { return false; }
     }
 
-    public bool Compare(object objA, object objB)
+    private bool Compare(object objA, object objB)
     {
       if (objA == null && objB == null)
         return true;
@@ -130,11 +168,26 @@ namespace Newtonsoft.Json.Linq
       return new JValue(this);
     }
 
+    /// <summary>
+    /// Creates a <see cref="JValue"/> comment with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
+    /// <returns></returns>
     public static JValue CreateComment(string value)
     {
       return new JValue(value, JsonTokenType.Comment);
     }
 
+    /// <summary>
+    /// Creates a <see cref="JValue"/> string with the given value.
+    /// </summary>
+    /// <param name="value">The value.</param>
+    /// <returns></returns>
+    public static JValue CreateString(string value)
+    {
+      return new JValue(value, JsonTokenType.String);
+    }
+
     private static JsonTokenType GetValueType(JsonTokenType? current, object value)
     {
       if (value == null)
@@ -154,11 +207,19 @@ namespace Newtonsoft.Json.Linq
       throw new ArgumentException("Could not determin JSON object type for type {0}.".FormatWith(CultureInfo.InvariantCulture, value.GetType()));
     }
 
+    /// <summary>
+    /// Gets the node type for this <see cref="JToken"/>.
+    /// </summary>
+    /// <value>The type.</value>
     public override JsonTokenType Type
     {
       get { return _valueType; }
     }
 
+    /// <summary>
+    /// Gets or sets the underlying token value.
+    /// </summary>
+    /// <value>The underlying token value.</value>
     public object Value
     {
       get { return _value; }
@@ -174,11 +235,6 @@ namespace Newtonsoft.Json.Linq
       }
     }
 
-    public static JValue CreateString(string value)
-    {
-      return new JValue(value, JsonTokenType.String);
-    }
-
     private static void WriteConvertableValue(JsonWriter writer, IList<JsonConverter> converters, Action<object> _defaultWrite, object value)
     {
       JsonConverter matchingConverter;
@@ -190,6 +246,11 @@ namespace Newtonsoft.Json.Linq
         _defaultWrite(value);
     }
 
+    /// <summary>
+    /// Writes this token to a <see cref="JsonWriter"/>.
+    /// </summary>
+    /// <param name="writer">A <see cref="JsonWriter"/> into which this method will write.</param>
+    /// <param name="converters">A collection of <see cref="JsonConverter"/> which will be used when writing the token.</param>
     public override void WriteTo(JsonWriter writer, params JsonConverter[] converters)
     {
       switch (_valueType)

Src/Newtonsoft.Json/Linq/JsonTokenReader.cs

@@ -6,12 +6,19 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a reader that provides fast, non-cached, forward-only access to serialized Json data.
+  /// </summary>
   public class JsonTokenReader : JsonReader
   {
     private JToken _root;
     private JToken _parent;
     private JToken _current;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonTokenReader"/> class.
+    /// </summary>
+    /// <param name="token">The token to read from.</param>
     public JsonTokenReader(JToken token)
     {
       ValidationUtils.ArgumentNotNull(token, "token");
@@ -20,6 +27,10 @@ namespace Newtonsoft.Json.Linq
       _current = token;
     }
 
+    /// <summary>
+    /// Reads the next Json token from the stream.
+    /// </summary>
+    /// <returns></returns>
     public override bool Read()
     {
       if (CurrentState != State.Start)

Src/Newtonsoft.Json/Linq/JsonTokenType.cs

@@ -30,20 +30,62 @@ using System.Text;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Specifies the type of token.
+  /// </summary>
   public enum JsonTokenType
   {
+    /// <summary>
+    /// No token type has been set.
+    /// </summary>
     None,
+    /// <summary>
+    /// A JSON object.
+    /// </summary>
     Object,
+    /// <summary>
+    /// A JSON array.
+    /// </summary>
     Array,
+    /// <summary>
+    /// A JSON constructor.
+    /// </summary>
     Constructor,
+    /// <summary>
+    /// A JSON object property.
+    /// </summary>
     Property,
+    /// <summary>
+    /// A comment.
+    /// </summary>
     Comment,
+    /// <summary>
+    /// An integer value.
+    /// </summary>
     Integer,
+    /// <summary>
+    /// A float value.
+    /// </summary>
     Float,
+    /// <summary>
+    /// A string value.
+    /// </summary>
     String,
+    /// <summary>
+    /// A boolean value.
+    /// </summary>
     Boolean,
+    /// <summary>
+    /// A null value.
+    /// </summary>
     Null,
+    /// <summary>
+    /// An undefined value.
+    /// </summary>
     Undefined,
+    /// <summary>
+    /// A date value.
+    /// </summary>
     Date
   }
-}
+}

Src/Newtonsoft.Json/Linq/JsonTokenWriter.cs

@@ -6,16 +6,27 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Linq
 {
+  /// <summary>
+  /// Represents a writer that provides a fast, non-cached, forward-only way of generating Json data.
+  /// </summary>
   public class JsonTokenWriter : JsonWriter
   {
     private JContainer _token;
     private JContainer _parent;
 
+    /// <summary>
+    /// Gets the token being writen.
+    /// </summary>
+    /// <value>The token being writen.</value>
     public JContainer Token
     {
       get { return _token; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonTokenWriter"/> class writing to the given <see cref="JContainer"/>.
+    /// </summary>
+    /// <param name="container">The container being written to.</param>
     public JsonTokenWriter(JContainer container)
     {
       ValidationUtils.ArgumentNotNull(container, "container");
@@ -24,6 +35,9 @@ namespace Newtonsoft.Json.Linq
       _parent = container;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JsonTokenWriter"/> class.
+    /// </summary>
     public JsonTokenWriter()
     {
     }
@@ -81,6 +95,10 @@ namespace Newtonsoft.Json.Linq
       AddParent(new JArray());
     }
 
+    /// <summary>
+    /// Writes the start of a constructor with the given name.
+    /// </summary>
+    /// <param name="name">The name of the constructor.</param>
     public override void WriteStartConstructor(string name)
     {
       base.WriteStartConstructor(name);
@@ -88,6 +106,10 @@ namespace Newtonsoft.Json.Linq
       AddParent(new JConstructor());
     }
 
+    /// <summary>
+    /// Writes the end.
+    /// </summary>
+    /// <param name="token">The token.</param>
     protected override void WriteEnd(JsonToken token)
     {
       RemoveParent();

Src/Newtonsoft.Json/MemberSerialization.cs

@@ -30,9 +30,18 @@ using System.Text;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Specifies the member serialization options for the <see cref="JsonSerializer"/>.
+  /// </summary>
   public enum MemberSerialization
   {
+    /// <summary>
+    /// All members are serialized by default. Members can be excluded using the <see cref="JsonIgnoreAttribute"/>.
+    /// </summary>
     OptOut,
+    /// <summary>
+    /// Only members must be marked with the <see cref="JsonPropertyAttribute"/> are serialized.
+    /// </summary>
     OptIn
   }
 }

Src/Newtonsoft.Json/MissingMemberHandling.cs

@@ -29,6 +29,9 @@ using System.Text;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Specifies missing member handling options for the <see cref="JsonSerializer"/>.
+  /// </summary>
   public enum MissingMemberHandling
   {
     /// <summary>

Src/Newtonsoft.Json/NullValueHandling.cs

@@ -31,7 +31,7 @@ using System.Text;
 namespace Newtonsoft.Json
 {
   /// <summary>
-  /// Specifies null value handling options for the <see cref="JsonWriter"/>.
+  /// Specifies null value handling options for the <see cref="JsonSerializer"/>.
   /// </summary>
   public enum NullValueHandling
   {

Src/Newtonsoft.Json/ObjectCreationHandling.cs

@@ -30,10 +30,22 @@ using System.Text;
 
 namespace Newtonsoft.Json
 {
+  /// <summary>
+  /// Specifies how object creation is handled by the <see cref="JsonSerializer"/>.
+  /// </summary>
   public enum ObjectCreationHandling
   {
+    /// <summary>
+    /// Reuse existing objects, create new objects when needed.
+    /// </summary>
     Auto = 0,
+    /// <summary>
+    /// Only reuse existing objects.
+    /// </summary>
     Reuse = 1,
+    /// <summary>
+    /// Always create new objects.
+    /// </summary>
     Replace = 2
   }
 }