Added doc-comments for main API

- Coherence-Signed#75

Author: DamianEdwards

src/Microsoft.Extensions.Configuration.Abstractions/IConfiguration.cs

@@ -6,12 +6,33 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Represents a set of key/value application configuration properties.
+    /// </summary>
     public interface IConfiguration
     {
+        /// <summary>
+        /// Gets or sets a configuration value.
+        /// </summary>
+        /// <param name="key">The configuration key.</param>
+        /// <returns>The configuration value.</returns>
         string this[string key] { get; set; }
 
+        /// <summary>
+        /// Gets a configuration sub-section with the specified key.
+        /// </summary>
+        /// <param name="key">The key of the configuration section.</param>
+        /// <returns>The <see cref="IConfigurationSection"/>.</returns>
+        /// <remarks>
+        ///     This method will never return <c>null</c>. If no matching sub-section is found with the specified key,
+        ///     an empty <see cref="IConfigurationSection"/> will be returned.
+        /// </remarks>
         IConfigurationSection GetSection(string key);
 
+        /// <summary>
+        /// Gets the immediate descendant configuration sub-sections.
+        /// </summary>
+        /// <returns>The configuration sub-sections.</returns>
         IEnumerable<IConfigurationSection> GetChildren();
 
         IChangeToken GetReloadToken();

src/Microsoft.Extensions.Configuration.Abstractions/IConfigurationBuilder.cs

@@ -5,14 +5,34 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Represents a type used to build application configuration.
+    /// </summary>
     public interface IConfigurationBuilder
     {
+        /// <summary>
+        /// Gets a key/value collection that can be used to share data between the <see cref="IConfigurationBuilder"/>
+        /// and the registered <see cref="IConfigurationProvider"/>s.
+        /// </summary>
         Dictionary<string, object> Properties { get; }
 
+        /// <summary>
+        /// Gets the providers used to obtain configuation values
+        /// </summary>
         IEnumerable<IConfigurationProvider> Providers { get; }
 
+        /// <summary>
+        /// Adds a new configuration provider.
+        /// </summary>
+        /// <param name="provider">The configuration provider to add.</param>
+        /// <returns>The same <see cref="IConfigurationBuilder"/>.</returns>
         IConfigurationBuilder Add(IConfigurationProvider provider);
 
+        /// <summary>
+        /// Builds an <see cref="IConfiguration"/> with keys and values from the set of providers registered in
+        /// <see cref="Providers"/>.
+        /// </summary>
+        /// <returns>An <see cref="IConfigurationRoot"/> with keys and values from the registered providers.</returns>
         IConfigurationRoot Build();
     }
 }

src/Microsoft.Extensions.Configuration.Abstractions/IConfigurationProvider.cs

@@ -5,17 +5,40 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Represents a source of configuration key/values for an application.
+    /// </summary>
     public interface IConfigurationProvider
     {
+        /// <summary>
+        /// Tries to get a configuration value for the specified key.
+        /// </summary>
+        /// <param name="key">The key.</param>
+        /// <param name="value">The value.</param>
+        /// <returns><c>True</c> if a value for the specified key was found, otherwise <c>false</c>.</returns>
         bool TryGet(string key, out string value);
 
+        /// <summary>
+        /// Sets a configuration value for the specified key.
+        /// </summary>
+        /// <param name="key">The key.</param>
+        /// <param name="value">The value.</param>
         void Set(string key, string value);
 
+        /// <summary>
+        /// Loads configuration values from the source represented by this <see cref="IConfigurationProvider"/>.
+        /// </summary>
         void Load();
 
-        IEnumerable<string> GetChildKeys(
-            IEnumerable<string> earlierKeys,
-            string parentPath,
-            string delimiter);
+        /// <summary>
+        /// Returns the immediate descendant configuration keys for a given parent path based on this
+        /// <see cref="IConfigurationProvider"/>'s data and the set of keys returned by all the preceding
+        /// <see cref="IConfigurationProvider"/>s.
+        /// </summary>
+        /// <param name="earlierKeys">The child keys returned by the preceding providers for the same parent path.</param>
+        /// <param name="parentPath">The parent path.</param>
+        /// <param name="delimiter">The delimiter to use to identify keys in the <see cref="IConfigurationProvider"/>'s data.</param>
+        /// <returns>The child keys.</returns>
+        IEnumerable<string> GetChildKeys(IEnumerable<string> earlierKeys, string parentPath, string delimiter);
     }
 }

src/Microsoft.Extensions.Configuration.Abstractions/IConfigurationRoot.cs

@@ -3,8 +3,14 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Represents the root of an <see cref="IConfiguration"/> hierarchy.
+    /// </summary>
     public interface IConfigurationRoot : IConfiguration
     {
+        /// <summary>
+        /// Force the configuration values to be reloaded from the underlying <see cref="IConfigurationProvider"/>s.
+        /// </summary>
         void Reload();
     }
 }

src/Microsoft.Extensions.Configuration.Abstractions/IConfigurationSection.cs

@@ -1,13 +1,26 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
-
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Represents a section of application configuration values.
+    /// </summary>
     public interface IConfigurationSection : IConfiguration
     {
+        /// <summary>
+        /// Gets the key this section occupies in its parent.
+        /// </summary>
         string Key { get; }
+
+        /// <summary>
+        /// Gets the full path to this section within the <see cref="IConfiguration"/>.
+        /// </summary>
         string Path { get; }
+
+        /// <summary>
+        /// Gets or sets the section value.
+        /// </summary>
         string Value { get; set; }
     }
 }

src/Microsoft.Extensions.Configuration.EnvironmentVariables/EnvironmentVariablesExtensions.cs

@@ -5,14 +5,29 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Extension methods for registering <see cref="EnvironmentVariablesConfigurationProvider"/> with <see cref="IConfigurationBuilder"/>.
+    /// </summary>
     public static class EnvironmentVariablesExtensions
     {
+        /// <summary>
+        /// Adds an <see cref="IConfigurationProvider"/> that reads configuration values from environment variables.
+        /// </summary>
+        /// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
+        /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
         public static IConfigurationBuilder AddEnvironmentVariables(this IConfigurationBuilder configurationBuilder)
         {
             configurationBuilder.Add(new EnvironmentVariablesConfigurationProvider());
             return configurationBuilder;
         }
 
+        /// <summary>
+        /// Adds an <see cref="IConfigurationProvider"/> that reads configuration values from environment variables
+        /// with a specified prefix.
+        /// </summary>
+        /// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
+        /// <param name="prefix">The prefix that environment variable names must start with.</param>
+        /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
         public static IConfigurationBuilder AddEnvironmentVariables(
             this IConfigurationBuilder configurationBuilder,
             string prefix)

src/Microsoft.Extensions.Configuration.FileExtensions/FileConfigurationExtensions.cs

@@ -8,10 +8,10 @@ namespace Microsoft.Extensions.Configuration
     public static class FileConfigurationExtensions
     {
         /// <summary>
-        /// Sets the base path in <see cref="IConfigurationBuilder"/> for file based providers.
+        /// Sets the base path to discover files in for file-based providers.
         /// </summary>
         /// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
-        /// <param name="basePath">Absolute path of file based providers.
+        /// <param name="basePath">The absolute path of file-based providers.</param>
         /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
         public static IConfigurationBuilder SetBasePath(this IConfigurationBuilder configurationBuilder, string basePath)
         {
@@ -31,7 +31,7 @@ public static IConfigurationBuilder SetBasePath(this IConfigurationBuilder confi
         }
 
         /// <summary>
-        /// Gets the base path in <see cref="IConfigurationBuilder"/> for file based providers.
+        /// Gets the base path to discover files in for file-based providers.
         /// </summary>
         /// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
         /// <returns>The <see cref="IConfigurationBuilder"/>.</returns>

src/Microsoft.Extensions.Configuration/ConfigurationBuilder.cs

@@ -5,10 +5,16 @@
 
 namespace Microsoft.Extensions.Configuration
 {
+    /// <summary>
+    /// Used to build key/value based configuration settings for use in an application.
+    /// </summary>
     public class ConfigurationBuilder : IConfigurationBuilder
     {
         private readonly IList<IConfigurationProvider> _providers = new List<IConfigurationProvider>();
 
+        /// <summary>
+        /// Returns the providers used to obtain configuation values.
+        /// </summary>
         public IEnumerable<IConfigurationProvider> Providers
         {
             get
@@ -17,36 +23,45 @@ public IEnumerable<IConfigurationProvider> Providers
             }
         }
 
+        /// <summary>
+        /// Gets a key/value collection that can be used to share data between the <see cref="IConfigurationBuilder"/>
+        /// and the registered <see cref="IConfigurationProvider"/>s.
+        /// </summary>
         public Dictionary<string, object> Properties { get; } = new Dictionary<string, object>();
 
         /// <summary>
         /// Adds a new configuration provider.
         /// </summary>
-        /// <param name="configurationProvider">The configuration provider to add.</param>
-        /// <returns>The same configuration provider.</returns>
-        public IConfigurationBuilder Add(IConfigurationProvider configurationProvider)
+        /// <param name="provider">The configuration provider to add.</param>
+        /// <returns>The same <see cref="IConfigurationBuilder"/>.</returns>
+        public IConfigurationBuilder Add(IConfigurationProvider provider)
         {
-            return Add(configurationProvider, load: true);
+            return Add(provider, load: true);
         }
 
         /// <summary>
-        /// Adds a new configuration provider.
+        /// Adds a new provider to obtain configuration values from.
+        /// This method is intended only for test scenarios.
         /// </summary>
-        /// <param name="configurationProvider">The configuration provider to add.</param>
+        /// <param name="provider">The configuration provider to add.</param>
         /// <param name="load">If true, the configuration provider's <see cref="IConfigurationProvider.Load"/> method will
         ///  be called.</param>
-        /// <returns>The same configuration provider.</returns>
-        /// <remarks>This method is intended only for test scenarios.</remarks>
-        public IConfigurationBuilder Add(IConfigurationProvider configurationProvider, bool load)
+        /// <returns>The same <see cref="IConfigurationBuilder"/>.</returns>
+        public IConfigurationBuilder Add(IConfigurationProvider provider, bool load)
         {
             if (load)
             {
-                configurationProvider.Load();
+                provider.Load();
             }
-            _providers.Add(configurationProvider);
+            _providers.Add(provider);
             return this;
         }
 
+        /// <summary>
+        /// Builds an <see cref="IConfiguration"/> with keys and values from the set of providers registered in
+        /// <see cref="Providers"/>.
+        /// </summary>
+        /// <returns>An <see cref="IConfigurationRoot"/> with keys and values from the registered providers.</returns>
         public IConfigurationRoot Build()
         {
             return new ConfigurationRoot(_providers);