From ee281662c4fdc55f6d674f41aa227e70561f2984 Mon Sep 17 00:00:00 2001 From: JamesNK Date: Thu, 14 Aug 2008 07:50:48 +0000 Subject: [PATCH] -Added missing XML comments to new members/classes -Fixed culture warnings --- Src/Newtonsoft.Json/JsonConverterAttribute.cs | 11 ++++ Src/Newtonsoft.Json/Linq/JArray.cs | 57 ++++++++++++++++++- Src/Newtonsoft.Json/Linq/JObject.cs | 25 ++++++++ Src/Newtonsoft.Json/Linq/JToken.cs | 4 ++ .../Linq/JTokenEqualityComparer.cs | 17 ++++++ Src/Newtonsoft.Json/Utilities/ConvertUtils.cs | 13 ++--- 6 files changed, 119 insertions(+), 8 deletions(-) diff --git a/Src/Newtonsoft.Json/JsonConverterAttribute.cs b/Src/Newtonsoft.Json/JsonConverterAttribute.cs index 94998cb3..9ee2dcfa 100644 --- a/Src/Newtonsoft.Json/JsonConverterAttribute.cs +++ b/Src/Newtonsoft.Json/JsonConverterAttribute.cs @@ -7,16 +7,27 @@ using System.Globalization; namespace Newtonsoft.Json { + /// + /// Instructs the to use the specified when serializing the member or class. + /// [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Class, AllowMultiple = false)] public class JsonConverterAttribute : Attribute { private readonly Type _converterType; + /// + /// Gets the type of the converter. + /// + /// The type of the converter. public Type ConverterType { get { return _converterType; } } + /// + /// Initializes a new instance of the class. + /// + /// Type of the converter. public JsonConverterAttribute(Type converterType) { if (converterType == null) diff --git a/Src/Newtonsoft.Json/Linq/JArray.cs b/Src/Newtonsoft.Json/Linq/JArray.cs index 4d4e08b6..0251d8e3 100644 --- a/Src/Newtonsoft.Json/Linq/JArray.cs +++ b/Src/Newtonsoft.Json/Linq/JArray.cs @@ -189,6 +189,10 @@ namespace Newtonsoft.Json.Linq } } + /// + /// Gets or sets the at the specified index. + /// + /// public JToken this[int index] { get @@ -204,6 +208,13 @@ namespace Newtonsoft.Json.Linq #region IList Members + /// + /// Determines the index of a specific item in the . + /// + /// The object to locate in the . + /// + /// The index of if found in the list; otherwise, -1. + /// public int IndexOf(JToken item) { int index = 0; @@ -218,6 +229,14 @@ namespace Newtonsoft.Json.Linq return -1; } + /// + /// Inserts an item to the at the specified index. + /// + /// The zero-based index at which should be inserted. + /// The object to insert into the . + /// + /// is not a valid index in the . + /// The is read-only. public void Insert(int index, JToken item) { if (index == 0) @@ -231,6 +250,13 @@ namespace Newtonsoft.Json.Linq } } + /// + /// Removes the item at the specified index. + /// + /// The zero-based index of the item to remove. + /// + /// is not a valid index in the . + /// The is read-only. public void RemoveAt(int index) { if (index < 0) @@ -255,16 +281,32 @@ namespace Newtonsoft.Json.Linq #region ICollection Members + /// + /// Adds an item to the . + /// + /// The object to add to the . + /// The is read-only. public void Add(JToken item) { Add((object)item); } + /// + /// Removes all items from the . + /// + /// The is read-only. public void Clear() { RemoveAll(); } + /// + /// Determines whether the contains a specific value. + /// + /// The object to locate in the . + /// + /// true if is found in the ; otherwise, false. + /// public bool Contains(JToken item) { return Children().Contains(item); @@ -289,6 +331,11 @@ namespace Newtonsoft.Json.Linq } } + /// + /// Gets the number of elements contained in the . + /// + /// + /// The number of elements contained in the . public int Count { get { return Children().Count(); } @@ -299,7 +346,15 @@ namespace Newtonsoft.Json.Linq get { return false; } } - public bool Remove(JToken item) + /// + /// Removes the first occurrence of a specific object from the . + /// + /// The object to remove from the . + /// + /// true if was successfully removed from the ; otherwise, false. This method also returns false if is not found in the original . + /// + /// The is read-only. + public new bool Remove(JToken item) { if (!((ICollection)this).Contains(item)) return false; diff --git a/Src/Newtonsoft.Json/Linq/JObject.cs b/Src/Newtonsoft.Json/Linq/JObject.cs index 232e2e08..6ee5572e 100644 --- a/Src/Newtonsoft.Json/Linq/JObject.cs +++ b/Src/Newtonsoft.Json/Linq/JObject.cs @@ -153,6 +153,10 @@ namespace Newtonsoft.Json.Linq } } + /// + /// Gets or sets the with the specified property name. + /// + /// public JToken this[string propertyName] { get @@ -256,6 +260,11 @@ namespace Newtonsoft.Json.Linq } #region IDictionary Members + /// + /// Adds the specified property name. + /// + /// Name of the property. + /// The value. public void Add(string propertyName, JToken value) { Add(new JProperty(propertyName, value)); @@ -271,6 +280,11 @@ namespace Newtonsoft.Json.Linq get { throw new NotImplementedException(); } } + /// + /// Removes the specified property name. + /// + /// Name of the property. + /// public bool Remove(string propertyName) { JProperty property = Property(propertyName); @@ -281,6 +295,12 @@ namespace Newtonsoft.Json.Linq return true; } + /// + /// Tries the get value. + /// + /// Name of the property. + /// The value. + /// public bool TryGetValue(string propertyName, out JToken value) { JProperty property = Property(propertyName); @@ -341,6 +361,11 @@ namespace Newtonsoft.Json.Linq } } + /// + /// Gets the number of elements contained in the . + /// + /// + /// The number of elements contained in the . public int Count { get { return Children().Count(); } diff --git a/Src/Newtonsoft.Json/Linq/JToken.cs b/Src/Newtonsoft.Json/Linq/JToken.cs index b18d24fa..91b1ee1c 100644 --- a/Src/Newtonsoft.Json/Linq/JToken.cs +++ b/Src/Newtonsoft.Json/Linq/JToken.cs @@ -44,6 +44,10 @@ namespace Newtonsoft.Json.Linq internal JToken _next; private static JTokenEqualityComparer _equalityComparer; + /// + /// Gets a comparer that can compare two tokens for value equality. + /// + /// A that can compare two nodes for value equality. public static JTokenEqualityComparer EqualityComparer { get diff --git a/Src/Newtonsoft.Json/Linq/JTokenEqualityComparer.cs b/Src/Newtonsoft.Json/Linq/JTokenEqualityComparer.cs index 999ccbb7..0bc3efb4 100644 --- a/Src/Newtonsoft.Json/Linq/JTokenEqualityComparer.cs +++ b/Src/Newtonsoft.Json/Linq/JTokenEqualityComparer.cs @@ -5,13 +5,30 @@ using System.Text; namespace Newtonsoft.Json.Linq { + /// + /// Compares tokens to determine whether they are equal. + /// public class JTokenEqualityComparer : IEqualityComparer { + /// + /// Determines whether the specified objects are equal. + /// + /// The first object of type to compare. + /// The second object of type to compare. + /// + /// true if the specified objects are equal; otherwise, false. + /// public bool Equals(JToken x, JToken y) { return JToken.DeepEquals(x, y); } + /// + /// Returns a hash code for the specified object. + /// + /// The for which a hash code is to be returned. + /// A hash code for the specified object. + /// The type of is a reference type and is null. public int GetHashCode(JToken obj) { if (obj == null) diff --git a/Src/Newtonsoft.Json/Utilities/ConvertUtils.cs b/Src/Newtonsoft.Json/Utilities/ConvertUtils.cs index ecb03a4d..426dabe7 100644 --- a/Src/Newtonsoft.Json/Utilities/ConvertUtils.cs +++ b/Src/Newtonsoft.Json/Utilities/ConvertUtils.cs @@ -79,7 +79,7 @@ namespace Newtonsoft.Json.Utilities return initialValue; if (targetType.IsInterface || targetType.IsGenericTypeDefinition || targetType.IsAbstract) - throw new ArgumentException(string.Format("Target type {0} is not a value type or a non-abstract class.", targetType), "targetType"); + throw new ArgumentException("Target type {0} is not a value type or a non-abstract class.".FormatWith(CultureInfo.InvariantCulture, targetType), "targetType"); // use Convert.ChangeType if both types are IConvertible @@ -131,7 +131,7 @@ namespace Newtonsoft.Json.Utilities if (ReflectionUtils.IsNullable(targetType)) return EnsureTypeAssignable(null, initialType, targetType); else - throw new Exception(string.Format("Can not convert null {0} into non-nullable {1}.", initialType, targetType)); + throw new Exception("Can not convert null {0} into non-nullable {1}.".FormatWith(CultureInfo.InvariantCulture, initialType, targetType)); } #if !SILVERLIGHT else if (initialValue is INullable) @@ -140,7 +140,7 @@ namespace Newtonsoft.Json.Utilities } #endif - throw new Exception(string.Format("Can not convert from {0} to {1}.", initialType, targetType)); + throw new Exception("Can not convert from {0} to {1}.".FormatWith(CultureInfo.InvariantCulture, initialType, targetType)); } #endregion @@ -287,7 +287,7 @@ namespace Newtonsoft.Json.Utilities /// /// The value to convert. /// The culture to use when converting. - /// The type to convert the value to. + /// The type to convert the value to. /// The converted value if the conversion was successful or the default value of T if it failed. /// /// true if initialValue was converted successfully or is assignable; otherwise, false. @@ -307,8 +307,7 @@ namespace Newtonsoft.Json.Utilities else if (value == null && ReflectionUtils.IsNullable(targetType)) return null; else - throw new Exception(string.Format("Could not cast or convert from {0} to {1}.", - (initialType != null) ? initialType.ToString() : "{null}", targetType)); + throw new Exception("Could not cast or convert from {0} to {1}.".FormatWith(CultureInfo.InvariantCulture, (initialType != null) ? initialType.ToString() : "{null}", targetType)); } #if !SILVERLIGHT @@ -327,7 +326,7 @@ namespace Newtonsoft.Json.Utilities else if (nullableValue is SqlDateTime) return ToValue((SqlDateTime)nullableValue); - throw new Exception(string.Format("Unsupported INullable type: {0}", nullableValue.GetType())); + throw new Exception("Unsupported INullable type: {0}".FormatWith(CultureInfo.InvariantCulture, nullableValue.GetType())); } #endif