1 files changed, 151 insertions, 52 deletions
diff --git a/src/DotNetOAuth/Messaging/Reflection/MessageDictionary.cs b/src/DotNetOAuth/Messaging/Reflection/MessageDictionary.cs
index 196af54..3c233ce 100644
--- a/src/DotNetOAuth/Messaging/Reflection/MessageDictionary.cs
+++ b/src/DotNetOAuth/Messaging/Reflection/MessageDictionary.cs
@@ -16,10 +16,20 @@ namespace DotNetOAuth.Messaging.Reflection {
 	/// name/value pairs that have no properties associated with them.
 	/// </summary>
 	internal class MessageDictionary : IDictionary<string, string> {
+		/// <summary>
+		/// The <see cref="IProtocolMessage"/> instance manipulated by this dictionary.
+		/// </summary>
 		private IProtocolMessage message;
 
+		/// <summary>
+		/// The <see cref="MessageDescription"/> instance that describes the message type.
+		/// </summary>
 		private MessageDescription description;
 
+		/// <summary>
+		/// Initializes a new instance of the <see cref="MessageDictionary"/> class.
+		/// </summary>
+		/// <param name="message">The message instance whose values will be manipulated by this dictionary.</param>
 		internal MessageDictionary(IProtocolMessage message) {
 			if (message == null) {
 				throw new ArgumentNullException("message");
@@ -29,29 +39,29 @@ namespace DotNetOAuth.Messaging.Reflection {
 			this.description = MessageDescription.Get(message.GetType());
 		}
 
-		#region IDictionary<string,string> Members
+		#region ICollection<KeyValuePair<string,string>> Properties
 
-		public void Add(string key, string value) {
-			if (value == null) {
-				throw new ArgumentNullException("value");
-			}
-
-			MessagePart part;
-			if (this.description.Mapping.TryGetValue(key, out part)) {
-				if (part.IsNondefaultValueSet(this.message)) {
-					throw new ArgumentException(MessagingStrings.KeyAlreadyExists);
-				}
-				part.SetValue(this.message, value);
-			} else {
-				this.message.ExtraData.Add(key, value);
-			}
+		/// <summary>
+		/// Gets the number of explicitly set values in the message.
+		/// </summary>
+		public int Count {
+			get { return this.Keys.Count; }
 		}
 
-		public bool ContainsKey(string key) {
-			return this.message.ExtraData.ContainsKey(key) ||
-				(this.description.Mapping.ContainsKey(key) && this.description.Mapping[key].GetValue(this.message) != null);
+		/// <summary>
+		/// Gets a value indicating whether this message is read only.
+		/// </summary>
+		bool ICollection<KeyValuePair<string, string>>.IsReadOnly {
+			get { return false; }
 		}
 
+		#endregion
+
+		#region IDictionary<string,string> Properties
+
+		/// <summary>
+		/// Gets all the keys that have values associated with them.
+		/// </summary>
 		public ICollection<string> Keys {
 			get {
 				List<string> keys = new List<string>(this.message.ExtraData.Count + this.description.Mapping.Count);
@@ -70,30 +80,9 @@ namespace DotNetOAuth.Messaging.Reflection {
 			}
 		}
 
-		public bool Remove(string key) {
-			if (this.message.ExtraData.Remove(key)) {
-				return true;
-			} else {
-				MessagePart part;
-				if (this.description.Mapping.TryGetValue(key, out part)) {
-					if (part.GetValue(this.message) != null) {
-						part.SetValue(this.message, null);
-						return true;
-					}
-				}
-				return false;
-			}
-		}
-
-		public bool TryGetValue(string key, out string value) {
-			MessagePart part;
-			if (this.description.Mapping.TryGetValue(key, out part)) {
-				value = part.GetValue(this.message);
-				return true;
-			}
-			return this.message.ExtraData.TryGetValue(key, out value);
-		}
-
+		/// <summary>
+		/// Gets all the values.
+		/// </summary>
 		public ICollection<string> Values {
 			get {
 				List<string> values = new List<string>(this.message.ExtraData.Count + this.description.Mapping.Count);
@@ -112,6 +101,16 @@ namespace DotNetOAuth.Messaging.Reflection {
 			}
 		}
 
+		/// <summary>
+		/// Gets or sets a value for some named value.
+		/// </summary>
+		/// <param name="key">The serialized form of a name for the value to read or write.</param>
+		/// <returns>The named value.</returns>
+		/// <remarks>
+		/// If the key matches a declared property or field on the message type,
+		/// that type member is set.  Otherwise the key/value is stored in a
+		/// dictionary for extra (weakly typed) strings.
+		/// </remarks>
 		public string this[string key] {
 			get {
 				MessagePart part;
@@ -139,18 +138,106 @@ namespace DotNetOAuth.Messaging.Reflection {
 
 		#endregion
 
-		#region ICollection<KeyValuePair<string,string>> Members
+		#region IDictionary<string,string> Methods
+
+		/// <summary>
+		/// Adds a named value to the message.
+		/// </summary>
+		/// <param name="key">The serialized form of the name whose value is being set.</param>
+		/// <param name="value">The serialized form of the value.</param>
+		/// <exception cref="ArgumentException">
+		/// Thrown if <paramref name="key"/> already has a set value in this message.
+		/// </exception>
+		/// <exception cref="ArgumentNullException">
+		/// Thrown if <paramref name="value"/> is null.
+		/// </exception>
+		public void Add(string key, string value) {
+			if (value == null) {
+				throw new ArgumentNullException("value");
+			}
+
+			MessagePart part;
+			if (this.description.Mapping.TryGetValue(key, out part)) {
+				if (part.IsNondefaultValueSet(this.message)) {
+					throw new ArgumentException(MessagingStrings.KeyAlreadyExists);
+				}
+				part.SetValue(this.message, value);
+			} else {
+				this.message.ExtraData.Add(key, value);
+			}
+		}
+
+		/// <summary>
+		/// Checks whether some named parameter has a value set in the message.
+		/// </summary>
+		/// <param name="key">The serialized form of the message part's name.</param>
+		/// <returns>True if the parameter by the given name has a set value.  False otherwise.</returns>
+		public bool ContainsKey(string key) {
+			return this.message.ExtraData.ContainsKey(key) ||
+				(this.description.Mapping.ContainsKey(key) && this.description.Mapping[key].GetValue(this.message) != null);
+		}
+
+		/// <summary>
+		/// Removes a name and value from the message given its name.
+		/// </summary>
+		/// <param name="key">The serialized form of the name to remove.</param>
+		/// <returns>True if a message part by the given name was found and removed.  False otherwise.</returns>
+		public bool Remove(string key) {
+			if (this.message.ExtraData.Remove(key)) {
+				return true;
+			} else {
+				MessagePart part;
+				if (this.description.Mapping.TryGetValue(key, out part)) {
+					if (part.GetValue(this.message) != null) {
+						part.SetValue(this.message, null);
+						return true;
+					}
+				}
+				return false;
+			}
+		}
+
+		/// <summary>
+		/// Gets some named value if the key has a value.
+		/// </summary>
+		/// <param name="key">The name (in serialized form) of the value being sought.</param>
+		/// <param name="value">The variable where the value will be set.</param>
+		/// <returns>True if the key was found and <paramref name="value"/> was set.  False otherwise.</returns>
+		public bool TryGetValue(string key, out string value) {
+			MessagePart part;
+			if (this.description.Mapping.TryGetValue(key, out part)) {
+				value = part.GetValue(this.message);
+				return true;
+			}
+			return this.message.ExtraData.TryGetValue(key, out value);
+		}
+
+		#endregion
+
+		#region ICollection<KeyValuePair<string,string>> Methods
 
+		/// <summary>
+		/// Sets a named value in the message.
+		/// </summary>
+		/// <param name="item">The name-value pair to add.  The name is the serialized form of the key.</param>
 		public void Add(KeyValuePair<string, string> item) {
 			this.Add(item.Key, item.Value);
 		}
 
+		/// <summary>
+		/// Removes all values in the message.
+		/// </summary>
 		public void Clear() {
 			foreach (string key in this.Keys) {
 				this.Remove(key);
 			}
 		}
 
+		/// <summary>
+		/// Checks whether a named value has been set on the message.
+		/// </summary>
+		/// <param name="item">The name/value pair.</param>
+		/// <returns>True if the key exists and has the given value.  False otherwise.</returns>
 		public bool Contains(KeyValuePair<string, string> item) {
 			MessagePart part;
 			if (this.description.Mapping.TryGetValue(item.Key, out part)) {
@@ -160,20 +247,22 @@ namespace DotNetOAuth.Messaging.Reflection {
 			}
 		}
 
+		/// <summary>
+		/// Copies all the serializable data from the message to a key/value array.
+		/// </summary>
+		/// <param name="array">The array to copy to.</param>
+		/// <param name="arrayIndex">The index in the <paramref name="array"/> to begin copying to.</param>
 		void ICollection<KeyValuePair<string, string>>.CopyTo(KeyValuePair<string, string>[] array, int arrayIndex) {
 			foreach (var pair in (IDictionary<string, string>)this) {
 				array[arrayIndex++] = pair;
 			}
 		}
 
-		public int Count {
-			get { return this.Keys.Count; }
-		}
-
-		bool ICollection<KeyValuePair<string, string>>.IsReadOnly {
-			get { return false; }
-		}
-
+		/// <summary>
+		/// Removes a named value from the message if it exists.
+		/// </summary>
+		/// <param name="item">The serialized form of the name and value to remove.</param>
+		/// <returns>True if the name/value was found and removed.  False otherwise.</returns>
 		public bool Remove(KeyValuePair<string, string> item) {
 			// We use contains because that checks that the value is equal as well.
 			if (((ICollection<KeyValuePair<string, string>>)this).Contains(item)) {
@@ -187,8 +276,13 @@ namespace DotNetOAuth.Messaging.Reflection {
 
 		#region IEnumerable<KeyValuePair<string,string>> Members
 
+		/// <summary>
+		/// Gets an enumerator that generates KeyValuePair&lt;string, string&gt; instances
+		/// for all the key/value pairs that are set in the message.
+		/// </summary>
+		/// <returns>The enumerator that can generate the name/value pairs.</returns>
 		public IEnumerator<KeyValuePair<string, string>> GetEnumerator() {
-			foreach (string key in Keys) {
+			foreach (string key in this.Keys) {
 				yield return new KeyValuePair<string, string>(key, this[key]);
 			}
 		}
@@ -197,6 +291,11 @@ namespace DotNetOAuth.Messaging.Reflection {
 
 		#region IEnumerable Members
 
+		/// <summary>
+		/// Gets an enumerator that generates KeyValuePair&lt;string, string&gt; instances
+		/// for all the key/value pairs that are set in the message.
+		/// </summary>
+		/// <returns>The enumerator that can generate the name/value pairs.</returns>
 		IEnumerator System.Collections.IEnumerable.GetEnumerator() {
 			return ((IEnumerable<KeyValuePair<string, string>>)this).GetEnumerator();
 		}