Xmldoc updates.

Author: StephenMolloy

src/Azure/AzureKeyVaultConfigBuilder.cs

@@ -45,7 +45,7 @@ public class AzureKeyVaultConfigBuilder : KeyValueConfigBuilder
         /// <param name="config">A collection of the name/value pairs representing builder-specific attributes specified in the configuration for this provider.</param>
         protected override void LazyInitialize(string name, NameValueCollection config)
         {
-            // Default 'Optional' to false. base.Initialize() will override if specified in config.
+            // Default 'Optional' to false. base.LazyInitialize() will override if specified in config.
             Optional = false;
 
             base.LazyInitialize(name, config);
@@ -133,12 +133,22 @@ public override ICollection<KeyValuePair<string, string>> GetAllValues(string pr
             return d;
         }
 
+        /// <summary>
+        /// Makes a determination about whether the input key is valid for this builder and backing store.
+        /// </summary>
+        /// <param name="key">The string to be validated. May be partial.</param>
+        /// <returns>True if the string is valid. False if the string is not a valid key.</returns>
         public override bool ValidateKey(string key)
         {
             // Key Vault only allows alphanumerics and '-'. This builder also allows for one '/'.
             return Regex.IsMatch(key, "^[a-zA-Z0-9-]+(/?[a-zA-Z0-9-]+)?$");
         }
 
+        /// <summary>
+        /// Transforms the raw key to a new string just before updating items in Strict and Greedy modes.
+        /// </summary>
+        /// <param name="rawKey">The key as read from the incoming config section.</param>
+        /// <returns>The key string that will be left in the processed config section.</returns>
         public override string UpdateKey(string rawKey)
         {
             // Remove the version segment if it's there.

src/Base/KeyValueConfigBuilder.cs

@@ -74,9 +74,9 @@ public abstract class KeyValueConfigBuilder : ConfigurationBuilder
         /// <returns>True if the string is valid. False if the string is not a valid key.</returns>
         public virtual bool ValidateKey(string key) { return true; }
         /// <summary>
-        /// Transforms the raw key read from the config file to a new string when updating items in Strict and Greedy modes.
+        /// Transforms the raw key to a new string just before updating items in Strict and Greedy modes.
         /// </summary>
-        /// <param name="rawKey">The key as read from the incomming config section.</param>
+        /// <param name="rawKey">The key as read from the incoming config section.</param>
         /// <returns>The key string that will be left in the processed config section.</returns>
         public virtual string UpdateKey(string rawKey) { return rawKey; }
 
@@ -116,6 +116,11 @@ protected virtual void LazyInitialize(string name, NameValueCollection config)
             _lazyInitialized = true;
         }
 
+        /// <summary>
+        /// Perform token substitution on a config parameter passed through builder initialization using token values from appSettings.
+        /// </summary>
+        /// <param name="configName">The name of the parameter to be retrieved.</param>
+        /// <returns>The updated parameter value if it exists. Null otherwise.</returns>
         protected string UpdateConfigSettingWithAppSettings(string configName)
         {
             string configValue = _config[configName];

src/Base/SectionHandler.cs

@@ -13,15 +13,49 @@ internal interface ISectionHandler
         IEnumerator<KeyValuePair<string, object>> GetEnumerator();
     }
 
+    /// <summary>
+    /// A class to be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to .Net configuration sections.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="ConfigurationSection"/> that the implementing class can process.</typeparam>
     public abstract class SectionHandler<T> : ISectionHandler where T : ConfigurationSection
     {
+        /// <summary>
+        /// The <see cref="ConfigurationSection"/> instance being processed by this <see cref="SectionHandler{T}"/>.
+        /// </summary>
         public T ConfigSection { get; private set; }
-        public abstract void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null);
+
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs consisting of the existing key for a config value in the config section, and an object reference
+        /// for the key/value pair to be passed in to <see cref="InsertOrUpdate(string, string, string, object)"/> while processing the config section.</returns>
         public abstract IEnumerator<KeyValuePair<string, object>> GetEnumerator();
+
+        /// <summary>
+        /// Updates an existing config value in the assigned <see cref="ConfigSection"/> with a new key and a new value. The old config value
+        /// can be located using the <paramref name="oldKey"/> or <paramref name="oldItem"/> parameters. If an old config value is not
+        /// found, a new config value should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the config item.</param>
+        /// <param name="newValue">The updated value for the config item.</param>
+        /// <param name="oldKey">The old key name for the config item, or null.</param>
+        /// <param name="oldItem">A reference to the old key/value pair obtained by <see cref="GetEnumerator"/>, or null.</param>
+        public abstract void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null);
     }
 
+    /// <summary>
+    /// A class that can be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to <see cref="AppSettingsSection"/>.
+    /// </summary>
     public class AppSettingsSectionHandler : SectionHandler<AppSettingsSection>
     {
+        /// <summary>
+        /// Updates an existing app setting in the assigned <see cref="SectionHandler{T}.ConfigSection"/> with a new key and a new value. The old setting
+        /// can be located using the <paramref name="oldKey"/> parameter. If an old setting is not found, a new setting should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the app setting.</param>
+        /// <param name="newValue">The updated value for the app setting.</param>
+        /// <param name="oldKey">The old key name for the app setting, or null.</param>
+        /// <param name="oldItem">The old key name for the app setting, or null., or null.</param>
         public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null)
         {
             if (newValue != null)
@@ -34,6 +68,10 @@ public override void InsertOrUpdate(string newKey, string newValue, string oldKe
             }
         }
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="SectionHandler{T}.ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs where both values of the pair are the existing key for each setting in the appSettings section.</returns>
         public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         {
             // Grab a copy of the keys array since we are using 'yield' and the Settings collection may change on us.
@@ -43,14 +81,26 @@ public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         }
     }
 
+    /// <summary>
+    /// A class that can be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to <see cref="ConnectionStringsSection"/>.
+    /// </summary>
     public class ConnectionStringsSectionHandler : SectionHandler<ConnectionStringsSection>
     {
-        public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldValue = null)
+        /// <summary>
+        /// Updates an existing connection string in the assigned <see cref="SectionHandler{T}.ConfigSection"/> with a new name and a new value. The old
+        /// connection string can be located using the <paramref name="oldItem"/> parameter. If an old connection string is not found, a new connection
+        /// string should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the connection string.</param>
+        /// <param name="newValue">The updated value for the connection string.</param>
+        /// <param name="oldKey">The old key name for the connection string, or null.</param>
+        /// <param name="oldItem">A reference to the old <see cref="ConnectionStringSettings"/> object obtained by <see cref="GetEnumerator"/>, or null.</param>
+        public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null)
         {
             if (newValue != null)
             {
                 // Preserve the old entry if it exists, as it might have more than just name/connectionString attributes.
-                ConnectionStringSettings cs = (oldValue as ConnectionStringSettings) ?? new ConnectionStringSettings();
+                ConnectionStringSettings cs = (oldItem as ConnectionStringSettings) ?? new ConnectionStringSettings();
 
                 // Make sure there are no entries using the old or new name other than this one
                 ConfigSection.ConnectionStrings.Remove(oldKey);
@@ -63,6 +113,11 @@ public override void InsertOrUpdate(string newKey, string newValue, string oldKe
             }
         }
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="SectionHandler{T}.ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs where the key is the existing name for each setting in the connectionStrings section, and the value
+        /// is a reference to the <see cref="ConnectionStringSettings"/> object referred to by that name.</returns>
         public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         {
             // The ConnectionStrings collection may change on us while we enumerate. :/

src/Base/SectionHandlerSection.cs

@@ -6,16 +6,25 @@
 
 namespace Microsoft.Configuration.ConfigurationBuilders
 {
-    public class SectionHandlersSection : ConfigurationSection
+    /// <summary>
+    /// Provides programmatic access to the 'sectionHandlers' config section. This class can't be inherited.
+    /// </summary>
+    public sealed class SectionHandlersSection : ConfigurationSection
     {
         static readonly string handlerSectionName = "Microsoft.Configuration.ConfigurationBuilders.SectionHandlers";
 
+        /// <summary>
+        /// Gets the collection of <see cref="SectionHandler{T}" />s defined for processing config sections with <see cref="KeyValueConfigBuilder"/>s./>
+        /// </summary>
         [ConfigurationProperty("handlers", IsDefaultCollection = true, Options = ConfigurationPropertyOptions.IsDefaultCollection)]
-        protected ProviderSettingsCollection Handlers
+        public ProviderSettingsCollection Handlers
         {
             get { return (ProviderSettingsCollection)base["handlers"]; }
         }
 
+        /// <summary>
+        /// Used to initialize a default set of section handlers. (For the appSettings and connectionStrings sections.)
+        /// </summary>
         protected override void InitializeDefault()
         {
             // This only runs once at the top "parent" level of the config stack. If there is already an