address comments.

Author: sergey-shandar

src/ResourceManager/Common/Commands.Common.Strategies/AsyncCmdletExtensions.cs

@@ -23,13 +23,25 @@ namespace Microsoft.Azure.Commands.Common.Strategies
 {
     public static class AsyncCmdletExtensions
     {
+        /// <summary>
+        /// WriteVerbose function with formatting.
+        /// </summary>
+        /// <param name="cmdlet">Cmdlet</param>
+        /// <param name="message">message with formatting</param>
+        /// <param name="p">message parameters</param>
         public static void WriteVerbose(this IAsyncCmdlet cmdlet, string message, params object[] p)
             => cmdlet.WriteVerbose(string.Format(message, p));
 
-        public static string UpdateLocation(
-            this IState current, string location, IResourceConfig config)
-            => location ?? current.GetLocation(config) ?? "eastus";
-
+        /// <summary>
+        /// The function read current Azure state and update it according to the `parameters`.
+        /// </summary>
+        /// <typeparam name="TModel">A resource model type.</typeparam>
+        /// <param name="client">Azure SDK client.</param>
+        /// <param name="subscriptionId">Subbscription Id.</param>
+        /// <param name="parameters">Cmdlet parameters.</param>
+        /// <param name="asyncCmdlet">Asynchronous cmdlet interface.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns></returns>
         public static async Task<TModel> RunAsync<TModel>(
             this IClient client,
             string subscriptionId,
@@ -40,51 +52,56 @@ public static async Task<TModel> RunAsync<TModel>(
         {
             // create a DAG of configs.
             var config = await parameters.CreateConfigAsync();
-
-            // reade current Azure state.
+            // read current Azure state.
             var current = await config.GetStateAsync(client, cancellationToken);
-
             // update location.
             parameters.Location = current.UpdateLocation(parameters.Location, config);
-
             // update a DAG of configs.
             config = await parameters.CreateConfigAsync();
-
-            var engine = new SdkEngine(subscriptionId);
-            var target = config.GetTargetState(current, engine, parameters.Location);
-
+            // create a target.
+            var target = config.GetTargetState(
+                current, new SdkEngine(subscriptionId), parameters.Location);
+            // print paramaters to a verbose stream.
             foreach (var p in asyncCmdlet.Parameters)
             {
                 asyncCmdlet.WriteVerbose(p.Key + " = " + ToPowerShellString(p.Value));
             }
 
-            // apply target state
+            // apply the target state
             var newState = await config.UpdateStateAsync(
                 client,
                 target,
                 cancellationToken,
                 new ShouldProcess(asyncCmdlet),
                 asyncCmdlet.ReportTaskProgress);
-
+            // return a resource model
             return newState.Get(config) ?? current.Get(config);
         }
 
+        static string UpdateLocation(
+            this IState current, string location, IResourceConfig config)
+            => location ?? current.GetLocation(config) ?? "eastus";
+
+
         static string ToPowerShellString(object value)
         {
             if (value == null)
             {
                 return "$null";
             }
+
             var s = value as string;
             if (s != null)
             {
                 return "\"" + s + "\"";
             }
+
             var e = value as IEnumerable;
             if (e != null)
             {
                 return string.Join(",", e.Cast<object>().Select(ToPowerShellString));
             }
+
             return value.ToString();
         }
 
@@ -128,8 +145,10 @@ public static void CmdletStartAndWait(
                                 var config = taskProgress.Config;
                                 activeTasks.Add(config.GetFullName());
                             }
+
                             progress += taskProgress.GetProgress();
                         }
+
                         var percent = (int)(progress * 100.0);
                         var r = new[] { "|", "/", "-", "\\" };
                         var x = r[DateTime.Now.Second % 4];

src/ResourceManager/Common/Commands.Common.Strategies/IAsyncCmdlet.cs

@@ -12,24 +12,47 @@
 // limitations under the License.
 // ----------------------------------------------------------------------------------
 
-using Microsoft.Azure.Commands.Common.Strategies;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
 namespace Microsoft.Azure.Commands.Common.Strategies
 {
+    /// <summary>
+    /// Asynchronous cmdlet interface.
+    /// </summary>
     public interface IAsyncCmdlet
     {
+        /// <summary>
+        /// Cmdlet parameters.
+        /// </summary>
         IEnumerable<KeyValuePair<string, object>> Parameters { get; }
 
+        /// <summary>
+        /// Thread-safe `WriteVerbose` function.
+        /// </summary>
+        /// <param name="message"></param>
         void WriteVerbose(string message);
 
+        /// <summary>
+        /// Asynchronous, thread-safe `ShouldProcess` function.
+        /// </summary>
         Task<bool> ShouldProcessAsync(string target, string action);
 
+        /// <summary>
+        /// Thread-safe `WriteVerbose` function.
+        /// </summary>
+        /// <param name="value"></param>
         void WriteObject(object value);
 
+        /// <summary>
+        /// Report task progress. The function is used to report current task and cmdlet progress.
+        /// </summary>
+        /// <param name="taskProgress"></param>
         void ReportTaskProgress(ITaskProgress taskProgress);
 
+        /// <summary>
+        /// A `New` verb.
+        /// </summary>
         string VerbsNew { get; }
     }
 }

src/ResourceManager/Common/Commands.Common.Strategies/ICmdlet.cs

@@ -16,19 +16,52 @@
 
 namespace Microsoft.Azure.Commands.Common.Strategies
 {
+    /// <summary>
+    /// An interface for a cmdlet for dependency injection.
+    /// </summary>
     public interface ICmdlet
     {
+        /// <summary>
+        /// Verbose output. See also PowerShell `WriteVerbose`.
+        /// </summary>
+        /// <param name="message"></param>
         void WriteVerbose(string message);
+
+        /// <summary>
+        /// See PowerShell `ShouldProcess`.
+        /// </summary>
+        /// <param name="target"></param>
+        /// <param name="action"></param>
+        /// <returns></returns>
         bool ShouldProcess(string target, string action);
+
+        /// <summary>
+        /// See also PowerShell `WriteObject`.
+        /// </summary>
+        /// <param name="value"></param>
         void WriteObject(object value);
+
+        /// <summary>
+        /// See also PowerShell `WriteProgress`.
+        /// </summary>
+        /// <param name="activity"></param>
+        /// <param name="statusDescription"></param>
+        /// <param name="currentOperation"></param>
+        /// <param name="percentComplete"></param>
         void WriteProgress(
             string activity,
             string statusDescription,
             string currentOperation,
             int percentComplete);
 
+        /// <summary>
+        /// See also `VerbsCommon.New`.
+        /// </summary>
         string VerbsNew { get; }
 
+        /// <summary>
+        /// Cmdlet parameters.
+        /// </summary>
         IEnumerable<KeyValuePair<string, object>> Parameters { get; }
     }
 }

src/ResourceManager/Common/Commands.Common.Strategies/IParameters.cs

@@ -16,11 +16,22 @@
 
 namespace Microsoft.Azure.Commands.Common.Strategies
 {
+    /// <summary>
+    /// Describes Azure operation parameter and a target resource.
+    /// </summary>
+    /// <typeparam name="TModel"></typeparam>
     public interface IParameters<TModel>
         where TModel : class
     {
+        /// <summary>
+        /// Azure location. For example, "eastus".
+        /// </summary>
         string Location { get; set; }
 
+        /// <summary>
+        /// Create an Azure resource configuration according to the parameters.
+        /// </summary>
+        /// <returns></returns>
         Task<ResourceConfig<TModel>> CreateConfigAsync();
     }
 }