Add some comments to explain how ConsoleApp parsing works

Author: ahmelsayed

src/Azure.Functions.Cli/ConsoleApp.cs

@@ -36,16 +36,21 @@ public static async Task RunAsync<T>(string[] args, IContainer container)
         {
             var app = new ConsoleApp(args, typeof(T).Assembly, container);
             var action = app.Parse();
+            // If all goes well, we will have an action to run.
+            // This action can be an actual action, or just a HelpAction, but this method doesn't care
+            // since HelpAction is still an IAction.
             if (action != null)
             {
                 try
                 {
+                    // All Actions are async. No return value is expected from any action.
                     await action.RunAsync();
                 }
                 catch (Exception ex)
                 {
                     if (Environment.GetEnvironmentVariable(Constants.CliDebug) == "1")
                     {
+                        // If CLI is in debug mode, display full call stack.
                         ColoredConsole.Error.WriteLine(ErrorColor(ex.ToString()));
                     }
                     else
@@ -56,19 +61,40 @@ public static async Task RunAsync<T>(string[] args, IContainer container)
             }
         }
 
+        /// <summary>
+        /// This function essentially takes in an IAction object, and builds the
+        /// command line that ought to be used to run that action but elevated.
+        /// The IAction however has to mention the name of each property that maps to
+        /// LongName and ShortName in the option Description. See InternalAction for an example.
+        /// This method also doesn't support actions that take an untyped paramater
+        /// like functionAppName, functionName, setting keys and values, storageAccount, etc.
+        /// </summary>
         public static bool RelaunchSelfElevated(IAction action, out string errors)
         {
+            // A command is:
+            //     func <context: optional> \
+            //          <subcontext: valid only if there is a context, optional> \
+            //          <action: not optional> --options
             errors = string.Empty;
             var attribute = action.GetType().GetCustomAttribute<ActionAttribute>();
             if (attribute != null)
             {
+                // First extract the contexts for the given action
                 Func<Context, string> getContext = c => c == Context.None ? string.Empty : c.ToString();
                 var context = getContext(attribute.Context);
                 var subContext = getContext(attribute.Context);
+
+                // Get the actual action name to use on the command line.
                 var name = attribute.Name;
+
+                // Every action is expected to return a ICommandLineParserResult that contains
+                // a collection UnMatchedOptions that the action accepts.
+                // That means this method doesn't support actions that have untyped ordered options.
+                // This however can be updated to support them easily just like help does now.
                 var args = action
                     .ParseArgs(Array.Empty<string>())
                     .UnMatchedOptions
+                    // Description is expected to contain the name of the POCO's property holding the value.
                     .Select(o => new { Name = o.Description, ParamName = o.HasLongName ? $"--{o.LongName}" : $"-{o.ShortName}" })
                     .Select(n =>
                     {
@@ -88,6 +114,10 @@ public static bool RelaunchSelfElevated(IAction action, out string errors)
 
                 var command = $"{context} {subContext} {name} {args}";
 
+                // Since the process will be elevated, we won't be able to redirect stdout\stdin to
+                // our process if we are not elevated too, which is most probably the case.
+                // Therefore I use shell redirection >> to a temp file, then read the content after
+                // the process exists.
                 var logFile = Path.GetTempFileName();
                 var exeName = Process.GetCurrentProcess().MainModule.FileName;
                 command = $"/c \"{exeName}\" {command} >> {logFile}";
@@ -117,38 +147,65 @@ internal ConsoleApp(string[] args, Assembly assembly, IContainer container)
         {
             _args = args;
             _container = container;
+            // TypeAttributePair is just a typed tuple of an IAction type and one of its action attribute.
             _actionAttributes = assembly
                 .GetTypes()
                 .Where(t => typeof(IAction).IsAssignableFrom(t) && !t.IsAbstract)
                 .Select(type => type.GetCustomAttributes<ActionAttribute>().Select(a => new TypeAttributePair { Type = type, Attribute = a }))
                 .SelectMany(i => i);
         }
 
+        /// <summary>
+        /// This method parses _args into an IAction.
+        /// </summary>
         internal IAction Parse()
         {
+            // If there is no args are passed, display help.
+            // If 1 arg is passed and it matched any of the strings in _helpArgs, display help.
+            // Otherwise, continue parsing.
             if (_args.Length == 0 ||
                 (_args.Length == 1 && _helpArgs.Any(ha => _args[0].Replace("-", "").Equals(ha, StringComparison.OrdinalIgnoreCase)))
                )
             {
                 return new HelpAction(_actionAttributes, CreateAction);
             }
 
+            // this supports the format:
+            //     `func help <context: optional> <subContext: optional> <action: optional>`
+            // but help has to be the first word. So `func azure help` for example doesn't work
+            // but `func help azure` should work.
             var isHelp = _args.First().Equals("help", StringComparison.OrdinalIgnoreCase)
                 ? true
                 : false;
-
-            var argsStack = new Stack<string>((isHelp ? _args.Skip(1) : _args).Reverse());
-            var contextStr = argsStack.Peek();
+ 
+            // We'll need to grab context arg: string, subcontext arg: string, action arg: string
+            var contextStr = string.Empty;
             var subContextStr = string.Empty;
+            var actionStr = string.Empty;
+
+            // These start out as None, but if contextStr and subContextStr hold a value, they'll
+            // get parsed into these
             var context = Context.None;
             var subContext = Context.None;
-            var actionStr = string.Empty;
+
+            // If isHelp, skip one and parse the rest of the command as usual.
+            var argsStack = new Stack<string>((isHelp ? _args.Skip(1) : _args).Reverse());
+
+            // Grab the first string, but don't pop it off the stack.
+            // If it's indeed a valid context, will remove it later.
+            // Otherwise, it could be just an action. Actions are allowed not to have contexts.
+            contextStr = argsStack.Peek();
 
             if (Enum.TryParse(contextStr, true, out context))
             {
+                // It is a valid context, so pop it out of the stack.
                 argsStack.Pop();
                 if (argsStack.Any())
                 {
+                    // We still have items in the stack, do the same again for subContext.
+                    // This means we only support 2 levels of contexts only. Main, and Sub.
+                    // There is currently no way to declaratively specify any more.
+                    // If we ever need more than 2 contexts, we should switch to a more generic mechanism.
                     subContextStr = argsStack.Peek();
                     if (Enum.TryParse(subContextStr, true, out subContext))
                     {
@@ -159,46 +216,72 @@ internal IAction Parse()
 
             if (argsStack.Any())
             {
+                // If there are still more items in the stack, then it's an actionStr
                 actionStr = argsStack.Pop();
             }
 
             if (string.IsNullOrEmpty(actionStr) || isHelp)
             {
+                // At this point we have all we need to create an IAction:
+                //    context
+                //    subContext
+                //    action
+                // However, if isHelp is true, then display help for that context.
+                // Action Name is ignored with help since we don't have action specific help yet.
+                // There is no need so far for action specific help since general context help displays
+                // the help for all the actions in that context anyway.
                 return new HelpAction(_actionAttributes, CreateAction, contextStr, subContextStr);
             }
 
+            // Find the matching action type.
+            // We expect to find 1 and only 1 IAction that matches all 3 (context, subContext, action)
             var actionType = _actionAttributes
                 .Where(a => a.Attribute.Name.Equals(actionStr, StringComparison.OrdinalIgnoreCase) &&
                             a.Attribute.Context == context && 
                             a.Attribute.SubContext == subContext)
                 .SingleOrDefault();
 
+            // If none is found, display help passing in all the info we have right now.
             if (actionType == null)
             {
                 return new HelpAction(_actionAttributes, CreateAction, contextStr, subContextStr);
             }
 
+            // Create the IAction
             var action = CreateAction(actionType.Type);
+
+            // Grab whatever is left in the stack of args into an array.
+            // This will be passed into the action as actions can optionally take args for their options.
             var args = argsStack.ToArray();
             try
             {
+                // Give the action a change to parse its args.
                 var parseResult = action.ParseArgs(args);
                 if (parseResult.HasErrors)
                 {
+                    // There was an error with the args, pass it to the HelpAction.
                     return new HelpAction(_actionAttributes, CreateAction, action, parseResult);
                 }
                 else
                 {
+                    // Action is ready to run.
                     return action;
                 }
             }
             catch (CliArgumentsException ex)
             {
+                // TODO: we can probably display help here as well.
+                // This happens for actions that expect an ordered untyped options.
                 ColoredConsole.Error.WriteLine(ex.Message);
                 return null;
             }
         }
 
+        /// <summary>
+        /// This method instantiates an IAction object from a Type.
+        /// It uses _container to injects dependencies into the created IAction if needed.
+        /// <param name="type"> Type is expected to be an IAction type </param>
+        /// </summary>
         internal IAction CreateAction(Type type)
         {
             var ctor = type.GetConstructors()?.SingleOrDefault();