-XML documentation

Src/Newtonsoft.Json.Tests/Bson/BsonReaderTests.cs

@@ -38,8 +38,7 @@ namespace Newtonsoft.Json.Tests.Bson
 {
   public class BsonReaderTests : TestFixtureBase
   {
-    private char pound = '\u00a3';
-    private char euro = '\u20ac';
+    private const char Euro = '\u20ac';
 
     [Test]
     public void ReadSingleObject()
@@ -829,7 +828,7 @@ namespace Newtonsoft.Json.Tests.Bson
       //sb.Append('1',127); //first char of euro at the end of the boundry.
       //sb.Append(euro, 5);
       //sb.Append('1',128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringValue(expected));
@@ -840,9 +839,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 127); //first char of euro at the end of the boundry.
-      sb.Append(euro, 5);
+      sb.Append(Euro, 5);
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringValue(expected));
@@ -853,9 +852,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 126);
-      sb.Append(euro, 5); //middle char of euro at the end of the boundry.
+      sb.Append(Euro, 5); //middle char of euro at the end of the boundry.
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       string result = WriteAndReadStringValue(expected);
@@ -866,7 +865,7 @@ namespace Newtonsoft.Json.Tests.Bson
     public void TestReadLenStringValueTripleByteCharOne()
     {
       StringBuilder sb = new StringBuilder();
-      sb.Append(euro, 1); //Just one triple byte char in the string.
+      sb.Append(Euro, 1); //Just one triple byte char in the string.
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringValue(expected));
@@ -877,9 +876,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 125);
-      sb.Append(euro, 5); //last char of the eruo at the end of the boundry.
+      sb.Append(Euro, 5); //last char of the eruo at the end of the boundry.
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringValue(expected));
@@ -908,7 +907,7 @@ namespace Newtonsoft.Json.Tests.Bson
       //sb.Append('1',127); //first char of euro at the end of the boundry.
       //sb.Append(euro, 5);
       //sb.Append('1',128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringPropertyName(expected));
@@ -919,9 +918,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 127); //first char of euro at the end of the boundry.
-      sb.Append(euro, 5);
+      sb.Append(Euro, 5);
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       string result = WriteAndReadStringPropertyName(expected);
@@ -933,9 +932,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 126);
-      sb.Append(euro, 5); //middle char of euro at the end of the boundry.
+      sb.Append(Euro, 5); //middle char of euro at the end of the boundry.
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringPropertyName(expected));
@@ -945,7 +944,7 @@ namespace Newtonsoft.Json.Tests.Bson
     public void TestReadStringPropertyNameTripleByteCharOne()
     {
       StringBuilder sb = new StringBuilder();
-      sb.Append(euro, 1); //Just one triple byte char in the string.
+      sb.Append(Euro, 1); //Just one triple byte char in the string.
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringPropertyName(expected));
@@ -956,9 +955,9 @@ namespace Newtonsoft.Json.Tests.Bson
     {
       StringBuilder sb = new StringBuilder();
       sb.Append('1', 125);
-      sb.Append(euro, 5); //last char of the eruo at the end of the boundry.
+      sb.Append(Euro, 5); //last char of the eruo at the end of the boundry.
       sb.Append('1', 128);
-      sb.Append(euro);
+      sb.Append(Euro);
 
       string expected = sb.ToString();
       Assert.AreEqual(expected, WriteAndReadStringPropertyName(expected));

Src/Newtonsoft.Json.Tests/Serialization/JsonSerializerTest.cs

@@ -3318,6 +3318,44 @@ keyword such as type of business.""
       Assert.AreEqual(27, deserialized.Age);
     }
 
+    public class Employee
+    {
+      public string Name { get; set; }
+      public Employee Manager { get; set; }
+
+      public bool ShouldSerializeManager()
+      {
+        return (Manager != this);
+      }
+    }
+
+    [Test]
+    public void ShouldSerializeExample()
+    {
+      Employee joe = new Employee();
+      joe.Name = "Joe Employee";
+      Employee mike = new Employee();
+      mike.Name = "Mike Manager";
+
+      joe.Manager = mike;
+      mike.Manager = mike;
+
+      string json = JsonConvert.SerializeObject(new []{ joe, mike }, Formatting.Indented);
+      // [
+      //   {
+      //     "Name": "Joe Employee",
+      //     "Manager": {
+      //       "Name": "Mike Manager"
+      //     }
+      //   },
+      //   {
+      //     "Name": "Mike Manager"
+      //   }
+      // ]
+
+      Console.WriteLine(json);
+    }
+
     public class DictionaryKey
     {
       public string Value { get; set; }

Src/Newtonsoft.Json/Bson/BsonObjectId.cs

@@ -31,10 +31,21 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Bson
 {
+  /// <summary>
+  /// Represents a BSON Oid (object id).
+  /// </summary>
   public class BsonObjectId
   {
+    /// <summary>
+    /// Gets or sets the value of the Oid.
+    /// </summary>
+    /// <value>The value of the Oid.</value>
     public byte[] Value { get; private set; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BsonObjectId"/> class.
+    /// </summary>
+    /// <param name="value">The Oid value.</param>
     public BsonObjectId(byte[] value)
     {
       ValidationUtils.ArgumentNotNull(value, "value");

Src/Newtonsoft.Json/Bson/BsonWriter.cs

@@ -134,6 +134,10 @@ namespace Newtonsoft.Json.Bson
       AddParent(new BsonObject());
     }
 
+    /// <summary>
+    /// Writes the property name of a name/value pair on a Json object.
+    /// </summary>
+    /// <param name="name">The name of the property.</param>
     public override void WritePropertyName(string name)
     {
       base.WritePropertyName(name);

Src/Newtonsoft.Json/Converters/BsonObjectIdConverter.cs

@@ -8,8 +8,17 @@ using Newtonsoft.Json.Utilities;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts a <see cref="BsonObjectId"/> to and from JSON and BSON.
+  /// </summary>
   public class BsonObjectIdConverter : 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>
+    /// <param name="serializer">The calling serializer.</param>
     public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
     {
       BsonObjectId objectId = (BsonObjectId) value;
@@ -25,6 +34,14 @@ namespace Newtonsoft.Json.Converters
       }
     }
 
+    /// <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>
+    /// <param name="existingValue">The existing value of object being read.</param>
+    /// <param name="serializer">The calling serializer.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
     {
       if (reader.TokenType != JsonToken.Bytes)
@@ -35,6 +52,13 @@ namespace Newtonsoft.Json.Converters
       return new BsonObjectId(value);
     }
 
+    /// <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 (objectType == typeof (BsonObjectId));

Src/Newtonsoft.Json/Converters/DataTableConverter.cs

@@ -65,6 +65,7 @@ namespace Newtonsoft.Json.Converters
     /// </summary>
     /// <param name="reader">The <see cref="JsonReader"/> to read from.</param>
     /// <param name="objectType">Type of the object.</param>
+    /// <param name="existingValue">The existing value of object being read.</param>
     /// <param name="serializer">The calling serializer.</param>
     /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)

Src/Newtonsoft.Json/Converters/RegexConverter.cs

@@ -7,8 +7,17 @@ using Newtonsoft.Json.Bson;
 
 namespace Newtonsoft.Json.Converters
 {
+  /// <summary>
+  /// Converts a <see cref="Regex"/> to and from JSON and BSON.
+  /// </summary>
   public class RegexConverter : 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>
+    /// <param name="serializer">The calling serializer.</param>
     public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
     {
       Regex regex = (Regex) value;
@@ -63,6 +72,14 @@ namespace Newtonsoft.Json.Converters
       writer.WriteEndObject();
     }
 
+    /// <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>
+    /// <param name="existingValue">The existing value of object being read.</param>
+    /// <param name="serializer">The calling serializer.</param>
+    /// <returns>The object value.</returns>
     public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
     {
       BsonReader bsonReader = reader as BsonReader;
@@ -119,6 +136,13 @@ namespace Newtonsoft.Json.Converters
       return new Regex(pattern, (RegexOptions)options);
     }
 
+    /// <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 (objectType == typeof (Regex));

Src/Newtonsoft.Json/JsonConvert.cs

@@ -739,17 +739,52 @@ namespace Newtonsoft.Json
     }
 
 #if !NET20 && !SILVERLIGHT
+    /// <summary>
+    /// Serializes the <see cref="XNode"/> to a JSON string.
+    /// </summary>
+    /// <param name="node">The node to convert to JSON.</param>
+    /// <returns>A JSON string of the XNode.</returns>
     public static string SerializeXNode(XObject node)
     {
       return SerializeXNode(node, Formatting.None);
     }
 
+    /// <summary>
+    /// Serializes the <see cref="XNode"/> to a JSON string.
+    /// </summary>
+    /// <param name="node">The node to convert to JSON.</param>
+    /// <param name="formatting">Indicates how the output is formatted.</param>
+    /// <returns>A JSON string of the XNode.</returns>
     public static string SerializeXNode(XObject node, Formatting formatting)
     {
       XmlNodeConverter converter = new XmlNodeConverter();
 
       return SerializeObject(node, formatting, converter);
     }
+
+    /// <summary>
+    /// Deserializes the <see cref="XNode"/> from a JSON string.
+    /// </summary>
+    /// <param name="value">The JSON string.</param>
+    /// <returns>The deserialized XNode</returns>
+    public static XDocument DeserializeXNode(string value)
+    {
+      return DeserializeXNode(value, null);
+    }
+
+    /// <summary>
+    /// Deserializes the <see cref="XNode"/> from a JSON string nested in a root elment.
+    /// </summary>
+    /// <param name="value">The JSON string.</param>
+    /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>
+    /// <returns>The deserialized XNode</returns>
+    public static XDocument DeserializeXNode(string value, string deserializeRootElementName)
+    {
+      XmlNodeConverter converter = new XmlNodeConverter();
+      converter.DeserializeRootElementName = deserializeRootElementName;
+
+      return (XDocument)DeserializeObject(value, typeof(XDocument), converter);
+    }
 #endif
 
 #if !SILVERLIGHT
@@ -799,32 +834,6 @@ namespace Newtonsoft.Json
 
       return (XmlDocument)DeserializeObject(value, typeof(XmlDocument), converter);
     }
-
-#if !NET20
-    /// <summary>
-    /// Deserializes the XNode from a JSON string.
-    /// </summary>
-    /// <param name="value">The JSON string.</param>
-    /// <returns>The deserialized XmlNode</returns>
-    public static XDocument DeserializeXNode(string value)
-    {
-      return DeserializeXNode(value, null);
-    }
-
-    /// <summary>
-    /// Deserializes the XmlNode from a JSON string nested in a root elment.
-    /// </summary>
-    /// <param name="value">The JSON string.</param>
-    /// <param name="deserializeRootElementName">The name of the root element to append when deserializing.</param>
-    /// <returns>The deserialized XmlNode</returns>
-    public static XDocument DeserializeXNode(string value, string deserializeRootElementName)
-    {
-      XmlNodeConverter converter = new XmlNodeConverter();
-      converter.DeserializeRootElementName = deserializeRootElementName;
-
-      return (XDocument)DeserializeObject(value, typeof(XDocument), converter);
-    }
-#endif
 #endif
   }
 }

Src/Newtonsoft.Json/JsonPropertyAttribute.cs

@@ -57,6 +57,10 @@ namespace Newtonsoft.Json
       set { _objectCreationHandling = value; }
     }
 
+    /// <summary>
+    /// Gets or sets the type name handling used when serializing this property.
+    /// </summary>
+    /// <value>The type name handling.</value>
     public TypeNameHandling TypeNameHandling
     {
       get { return _typeNameHandling ?? default(TypeNameHandling); }

Src/Newtonsoft.Json/Serialization/JsonProperty.cs

@@ -125,10 +125,18 @@ namespace Newtonsoft.Json.Serialization
     /// <value>The object creation handling.</value>
     public ObjectCreationHandling? ObjectCreationHandling { get; set; }
 
-    public Predicate<object> ShouldSerialize { get; set; }
-
+    /// <summary>
+    /// Gets or sets the type name handling.
+    /// </summary>
+    /// <value>The type name handling.</value>
     public TypeNameHandling? TypeNameHandling { get; set; }
 
+    /// <summary>
+    /// Gets or sets a predicate used to determine whether the property should be serialize.
+    /// </summary>
+    /// <value>A predicate used to determine whether the property should be serialize.</value>
+    public Predicate<object> ShouldSerialize { get; set; }
+
     /// <summary>
     /// Returns a <see cref="String"/> that represents this instance.
     /// </summary>

Src/Newtonsoft.Json/Utilities/ILGeneratorExtensions.cs

@@ -33,7 +33,7 @@ using System.Reflection;
 
 namespace Newtonsoft.Json.Utilities
 {
-  public static class ILGeneratorExtensions
+  internal static class ILGeneratorExtensions
   {
     public static void PushInstance(this ILGenerator generator, Type type)
     {