Updated interface documentation for non-provider interfaces (the simple cases)

Author: sharwell

src/corelib/Core/Caching/UserAccessCache.cs

@@ -5,12 +5,46 @@
 
 namespace net.openstack.Core.Caching
 {
+    /// <summary>
+    /// Provides a thread-safe cache of <see cref="UserAccess"/> objects. A default shared
+    /// instance is available through <see cref="UserAccessCache.Instance"/>.
+    /// </summary>
     public class UserAccessCache : ICache<UserAccess>
     {
         private static readonly Lazy<UserAccessCache> _instance = new Lazy<UserAccessCache>(CreateInstance, true);
 
         private readonly ConcurrentDictionary<string, UserAccess> _tokenCache = new ConcurrentDictionary<string, UserAccess>();
 
+        /// <summary>
+        /// Gets a <see cref="UserAccess"/> cached for a particular key, updating the value if necessary.
+        /// </summary>
+        /// <remarks>
+        /// This method returns a previously cached <see cref="UserAccess"/> when possible. If any
+        /// of the following conditions are met, the <paramref name="refreshCallback"/> function
+        /// will be called to obtain a new value for <paramref name="key"/> which is then added to
+        /// the cache, replacing any previously cached value.
+        /// 
+        /// <list type="bullet">
+        /// <item>The cache does not contain any value associated with <paramref name="key"/>.</item>
+        /// <item><paramref name="forceCacheRefresh"/> is <c>true</c>.</item>
+        /// <item>The previously cached <see cref="UserAccess"/> for <paramref name="key"/> has expired
+        /// (see <see cref="IdentityToken.IsExpired()"/>).</item>
+        /// </list>
+        ///
+        /// <para>If any of the above conditions is met and <paramref name="refreshCallback"/> is <c>null</c>,
+        /// the previously cached value for <paramref name="key"/>, if any, is removed from the cache
+        /// and the method returns <c>null</c>.</para>
+        /// </remarks>
+        /// <param name="key">The key.</param>
+        /// <param name="refreshCallback">A function which returns a new value for the specified <paramref name="key"/>,
+        /// or <c>null</c> if no update function available (see remarks). This function may perform a synchronous
+        /// authentication to an <see cref="IIdentityProvider"/>.</param>
+        /// <param name="forceCacheRefresh">If <c>true</c>, the value associated with <paramref name="key"/> will be always be refreshed by calling <paramref name="refreshCallback"/>, even if a value is already cached.</param>
+        /// <returns>
+        /// The cached <see cref="UserAccess"/> associated with the specified <paramref name="key"/>.
+        /// If no cached value is available (see remarks), the method returns <c>null</c>.
+        /// </returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="key"/> is <c>null</c>.</exception>
         public UserAccess Get(string key, Func<UserAccess> refreshCallback, bool forceCacheRefresh = false)
         {
             UserAccess userAccess;
@@ -64,6 +98,9 @@ public UserAccess Get(string key, Func<UserAccess> refreshCallback, bool forceCa
             return userAccess;
         }
 
+        /// <summary>
+        /// Gets a default instance of <see cref="UserAccessCache"/>.
+        /// </summary>
         public static UserAccessCache Instance
         {
             get
@@ -84,8 +121,40 @@ private static bool IsValid(UserAccess userAccess)
         }
     }
 
+    /// <summary>
+    /// Represents a thread-safe cache of objects identified by string keys.
+    /// </summary>
+    /// <typeparam name="T">Type type of objects stored in the cache.</typeparam>
     public interface ICache<T>
     {
+        /// <summary>
+        /// Gets a value cached for a particular key, updating the value if necessary.
+        /// </summary>
+        /// <remarks>
+        /// This method returns a previously cached value when possible. If any of the following
+        /// conditions are met, the <paramref name="refreshCallback"/> function will be called to
+        /// obtain a new value for <paramref name="key"/> which is then added to the cache,
+        /// replacing any previously cached value.
+        /// 
+        /// <list type="bullet">
+        /// <item>The cache does not contain any value associated with <paramref name="key"/>.</item>
+        /// <item><paramref name="forceCacheRefresh"/> is <c>true</c>.</item>
+        /// <item>The previously cached value for <paramref name="key"/> is no longer valid. The exact
+        /// algorithm for determining whether or not a value is valid in implementation-defined.</item>
+        /// </list>
+        ///
+        /// <para>If any of the above conditions is met and <paramref name="refreshCallback"/> is <c>null</c>,
+        /// the previously cached value for <paramref name="key"/>, if any, is removed from the cache
+        /// and the default value for <typeparamref name="T"/> is returned.</para>
+        /// </remarks>
+        /// <param name="key">The key.</param>
+        /// <param name="refreshCallback">A function which returns a new value for the specified <paramref name="key"/>, or <c>null</c> if no update function available (see remarks).</param>
+        /// <param name="forceCacheRefresh">If <c>true</c>, the value associated with <paramref name="key"/> will be always be refreshed by calling <paramref name="refreshCallback"/>, even if a value is already cached.</param>
+        /// <returns>
+        /// The cached value associated with the specified <paramref name="key"/>. If no cached value is
+        /// available (see remarks), the method returns the default value for <typeparamref name="T"/>.
+        /// </returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="key"/> is <c>null</c>.</exception>
         T Get(string key, Func<T> refreshCallback, bool forceCacheRefresh = false);
     }
 }

src/corelib/Core/Domain/Mapping/IJsonObjectMapper.cs

@@ -1,9 +1,23 @@
-using Newtonsoft.Json.Linq;
+using System;
+using Newtonsoft.Json.Linq;
 
 namespace net.openstack.Core.Domain.Mapping
 {
+    /// <summary>
+    /// Represents an object that can convert between generic <see cref="JObject"/> instances
+    /// and instances of another specific type.
+    /// </summary>
+    /// <typeparam name="T">The type which can be converted to and from <see cref="JObject"/>.</typeparam>
     public interface IJsonObjectMapper<T> : IObjectMapper<JObject, T>
     {
+        /// <summary>
+        /// Converts a JSON string representation of <typeparamref name="T"/> to an instance
+        /// of <typeparamref name="T"/>.
+        /// </summary>
+        /// <param name="rawJson">The JSON string representation.</param>
+        /// <returns>An instance of <typeparamref name="T"/> represented by <paramref name="rawJson"/>.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="rawJson"/> is <c>null</c>.</exception>
+        /// <exception cref="NotSupportedException">If the conversion cannot be performed.</exception>
         T Map(string rawJson);
     }
 }

src/corelib/Core/Domain/Mapping/IObjectMapper.cs

@@ -1,9 +1,41 @@
 namespace net.openstack.Core.Domain.Mapping
 {
+    using System;
+    using System.ComponentModel;
+
+    /// <summary>
+    /// Represents an object that can convert between instances of two specific types.
+    /// </summary>
+    /// <remarks>
+    /// This interface is similar to a <see cref="TypeConverter"/> which only supports
+    /// conversions between exactly two concrete types.
+    /// </remarks>
+    /// <typeparam name="TFrom">The first type.</typeparam>
+    /// <typeparam name="TTo">The second type.</typeparam>
     public interface IObjectMapper<TFrom, TTo>
     {
+        /// <summary>
+        /// Converts an instance of <typeparamref name="TFrom"/> to an instance of <typeparamref name="TTo"/>.
+        /// </summary>
+        /// <remarks>
+        /// This method provides behavior similar to a strongly-typed implementation
+        /// of <see cref="TypeConverter.ConvertTo(object, Type)"/>.
+        /// </remarks>
+        /// <param name="from">The instance to convert.</param>
+        /// <returns>The converted instance.</returns>
+        /// <exception cref="NotSupportedException">The conversion cannot be performed.</exception>
         TTo Map(TFrom from);
 
+        /// <summary>
+        /// Converts an instance of <typeparamref name="TTo"/> to an instance of <typeparamref name="TFrom"/>.
+        /// </summary>
+        /// <remarks>
+        /// This method provides behavior similar to a strongly-typed implementation
+        /// of <see cref="TypeConverter.ConvertFrom(object)"/>.
+        /// </remarks>
+        /// <param name="to">The instance to convert.</param>
+        /// <returns>The converted instance.</returns>
+        /// <exception cref="NotSupportedException">The conversion cannot be performed.</exception>
         TFrom Map(TTo to);
     }
-}
+}

src/corelib/Core/Domain/Mapping/NetworkResponseJsonMapper.cs

@@ -5,6 +5,7 @@ namespace net.openstack.Core.Domain.Mapping
 {
     internal class NetworkResponseJsonMapper : IJsonObjectMapper<Network>
     {
+        /// <inheritdoc/>
         public Network Map(JObject @from)
         {
             if (from == null)
@@ -18,11 +19,13 @@ public Network Map(JObject @from)
                 };
         }
 
+        /// <inheritdoc/>
         public JObject Map(Network to)
         {
             throw new System.NotImplementedException();
         }
 
+        /// <inheritdoc/>
         public Network Map(string rawJson)
         {
             if (string.IsNullOrWhiteSpace(rawJson))

src/corelib/Core/IEncodeDecodeProvider.cs

@@ -1,13 +1,26 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-
-namespace net.openstack.Core
+namespace net.openstack.Core
 {
+    /// <summary>
+    /// This interface provides methods for encoding and decoding strings which are
+    /// embedded in the query string section of a URL.
+    /// </summary>
     public interface IEncodeDecodeProvider
     {
+        /// <summary>
+        /// Encodes a string for inclusion in a URL.
+        /// </summary>
+        /// <remarks>
+        /// The encoded string can be restored by calling <see cref="UrlDecode"/>.
+        /// </remarks>
+        /// <param name="stringToEncode">The string to encode.</param>
+        /// <returns>The encoded string. If <paramref name="stringToEncode"/> is <c>null</c>, this method returns <c>null</c>.</returns>
         string UrlEncode(string stringToEncode);
+
+        /// <summary>
+        /// Decodes a string which is embedded in a URL.
+        /// </summary>
+        /// <param name="stringToDecode">The string to decode.</param>
+        /// <returns>The decoded string. If <paramref name="stringToDecode"/> is <c>null</c>, this method returns <c>null</c>.</returns>
         string UrlDecode(string stringToDecode);
     }
 }

src/corelib/Core/IObjectStorageMetadataProcessor.cs

@@ -1,10 +1,25 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using JSIStudios.SimpleRESTServices.Client;
 
 namespace net.openstack.Core
 {
+    /// <summary>
+    /// This interface represents an object that can extract metadata information from a
+    /// collection of HTTP headers returned from a REST request.
+    /// </summary>
     public interface IObjectStorageMetadataProcessor
     {
+        /// <summary>
+        /// Extracts metadata information from a collection of HTTP headers. The returned collection
+        /// may include multiple types of metadata information. The keys of the collection represent
+        /// the type of metadata, and the values are key-value collections of the corresponding
+        /// metadata.
+        /// </summary>
+        /// <param name="httpHeaders">The collection of HTTP headers.</param>
+        /// <returns>The metadata.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="httpHeaders"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="httpHeaders"/> contains two headers with equivalent values for <see cref="HttpHeader.Key"/> (case-insensitive).</exception>
         Dictionary<string, Dictionary<string, string>> ProcessMetadata(IList<HttpHeader> httpHeaders);
     }
 }

src/corelib/Core/Validators/IBlockStorageValidator.cs

@@ -1,7 +1,22 @@
 namespace net.openstack.Core.Validators
 {
+    using System;
+    using net.openstack.Core.Providers;
+    using net.openstack.Providers.Rackspace.Exceptions;
+
+    /// <summary>
+    /// Represents an object that validates arguments for an implementation of <see cref="IBlockStorageProvider"/>
+    /// prior to sending the calls to the underlying REST API.
+    /// </summary>
     public interface IBlockStorageValidator
     {
+        /// <summary>
+        /// Validates the <c>size</c> parameter when creating a new block storage volume
+        /// with <see cref="IBlockStorageProvider.CreateVolume"/>.
+        /// </summary>
+        /// <param name="size">The volume size in GB.</param>
+        /// <exception cref="ArgumentOutOfRangeException">If <paramref name="size"/> is less than 0.</exception>
+        /// <exception cref="InvalidVolumeSizeException">If <paramref name="size"/> is not a valid volume size.</exception>
         void ValidateVolumeSize(int size);
     }
 }

src/corelib/Core/Validators/INetworksValidator.cs

@@ -1,7 +1,21 @@
 namespace net.openstack.Core.Validators
 {
+    using System;
+    using net.openstack.Core.Exceptions;
+    using net.openstack.Core.Providers;
+
+    /// <summary>
+    /// Represents an object that validates arguments for an implementation of <see cref="INetworksProvider"/>
+    /// prior to sending the calls to the underlying REST API.
+    /// </summary>
     public interface INetworksValidator
     {
-        void ValidateCidr(string cidr);    
+        /// <summary>
+        /// Validates an IP address range (CIDR) formatted as a string.
+        /// </summary>
+        /// <param name="cidr">The IP address range.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="cidr"/> is <c>null</c>.</exception>
+        /// <exception cref="CidrFormatException">If <paramref name="cidr"/> is not in the correct format.</exception>
+        void ValidateCidr(string cidr);
     }
 }

src/corelib/Core/Validators/IObjectStorageValidator.cs

@@ -1,8 +1,29 @@
 namespace net.openstack.Core.Validators
 {
+    using System;
+    using net.openstack.Core.Exceptions;
+    using net.openstack.Core.Providers;
+
+    /// <summary>
+    /// Represents an object that validates arguments for an implementation of <see cref="IObjectStorageProvider"/>
+    /// prior to sending the calls to the underlying REST API.
+    /// </summary>
     public interface IObjectStorageValidator
     {
+        /// <summary>
+        /// Validates a container name for an object storage provider.
+        /// </summary>
+        /// <param name="containerName">The container name.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="containerName"/> is <c>null</c>.</exception>
+        /// <exception cref="ContainerNameException">If <paramref name="containerName"/> is not a valid container name.</exception>
         void ValidateContainerName(string containerName);
+
+        /// <summary>
+        /// Validates an object name for an object storage provider.
+        /// </summary>
+        /// <param name="objectName">The object name.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="objectName"/> is <c>null</c>.</exception>
+        /// <exception cref="ObjectNameException">If <paramref name="objectName"/> is not a valid object name.</exception>
         void ValidateObjectName(string objectName);
     }
-}
+}

src/corelib/Providers/Rackspace/CloudFilesMetadataProcessor.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using JSIStudios.SimpleRESTServices.Client;
 using net.openstack.Core;
 
@@ -22,8 +23,31 @@ public static CloudFilesMetadataProcessor Default
             }
         }
 
+        /// <summary>
+        /// Extracts metadata information from a collection of HTTP headers.
+        /// </summary>
+        /// <remarks>
+        /// The returned collection has two keys: <see cref="CloudFilesProvider.ProcessedHeadersHeaderKey"/>
+        /// and <see cref="CloudFilesProvider.ProcessedHeadersMetadataKey"/>.
+        ///
+        /// <para>The value for
+        /// <see cref="CloudFilesProvider.ProcessedHeadersMetadataKey"/> contains the processed Cloud Files
+        /// metadata included in HTTP headers such as <strong>X-Account-Meta-*</strong>,
+        /// <strong>X-Container-Meta-*</strong>, and <strong>X-Object-Meta-*</strong>. The metadata prefix
+        /// has been removed from the keys stored in this value.</para>
+        ///
+        /// <para>The value for <see cref="CloudFilesProvider.ProcessedHeadersHeaderKey"/> contains the
+        /// HTTP headers which were not in the form of a known Cloud Files metadata prefix.</para>
+        /// </remarks>
+        /// <param name="httpHeaders">The collection of HTTP headers.</param>
+        /// <returns>The metadata.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="httpHeaders"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="httpHeaders"/> contains two headers with equivalent values for <see cref="HttpHeader.Key"/> (case-insensitive).</exception>
         public virtual Dictionary<string, Dictionary<string, string>> ProcessMetadata(IList<HttpHeader> httpHeaders)
         {
+            if (httpHeaders == null)
+                throw new ArgumentNullException("httpHeaders");
+
             var pheaders = new Dictionary<string, string>();
             var metadata = new Dictionary<string, string>();
             foreach (var header in httpHeaders)