add - brk|doc - Added support for argument descriptions

---

Arguments need some descriptions as they're useful for documentation, so we've decided to add an extra entry that allows you to add description to your command arguments in almost the same way that you add descriptions to the switches.

---

Type: add
Breaking: True
Doc Required: True
Part: 1/1

Directory.Build.props

@@ -20,7 +20,7 @@
           changes!
         -->
         <NitrocidModAPIVersionMajor>3.0.26</NitrocidModAPIVersionMajor>
-        <NitrocidModAPIVersionChangeset>7</NitrocidModAPIVersionChangeset>
+        <NitrocidModAPIVersionChangeset>8</NitrocidModAPIVersionChangeset>
 
         <!-- The above two properties are to be installed to the file version -->
         <NitrocidModAPIVersion>$(NitrocidModAPIVersionMajor).$(NitrocidModAPIVersionChangeset)</NitrocidModAPIVersion>

public/Nitrocid/Shell/ShellBase/Arguments/ArgumentsParser.cs

@@ -335,7 +335,7 @@ private static (ProvidedArgumentsInfo satisfied, ProvidedArgumentsInfo[] total)
 
                     // Check to see if the argument expects a number and that the provided argument is numeric
                     // or if the argument allows string values
-                    if (argPart.IsNumeric && !double.TryParse(arg, out _))
+                    if (argPart.Options.IsNumeric && !double.TryParse(arg, out _))
                         numberProvided = false;
                 }
 
@@ -348,7 +348,7 @@ private static (ProvidedArgumentsInfo satisfied, ProvidedArgumentsInfo[] total)
 
                     // Check to see if the argument expects a number and that the provided argument is numeric
                     // or if the argument allows string values
-                    if (argPart.ExactWording.Length > 0 && !argPart.ExactWording.Contains(arg))
+                    if (argPart.Options.ExactWording.Length > 0 && !argPart.Options.ExactWording.Contains(arg))
                         exactWordingProvided = false;
                 }
 

public/Nitrocid/Shell/ShellBase/Arguments/CommandArgumentInfo.cs

@@ -114,8 +114,8 @@ public string RenderedUsage
                 foreach (var Argument in Arguments)
                 {
                     bool required = Argument.ArgumentRequired;
-                    bool justNumeric = Argument.IsNumeric;
-                    bool hasWordingRequirement = Argument.ExactWording.Length > 0;
+                    bool justNumeric = Argument.Options.IsNumeric;
+                    bool hasWordingRequirement = Argument.Options.ExactWording.Length > 0;
                     string requiredTagStart = hasWordingRequirement ? "" : required ? "<" : "[";
                     string requiredTagEnd = hasWordingRequirement ? "" : required ? ">" : "]";
                     string numericRender = justNumeric ? ":int" : "";

public/Nitrocid/Shell/ShellBase/Arguments/CommandArgumentPart.cs

@@ -36,17 +36,9 @@ public class CommandArgumentPart
         /// </summary>
         public string ArgumentExpression { get; private set; }
         /// <summary>
-        /// Auto completion function delegate
+        /// Argument options
         /// </summary>
-        public Func<string[], string[]> AutoCompleter { get; private set; }
-        /// <summary>
-        /// Command argument expression
-        /// </summary>
-        public bool IsNumeric { get; private set; }
-        /// <summary>
-        /// User is required to provide one of the exact wordings
-        /// </summary>
-        public string[] ExactWording { get; private set; }
+        public CommandArgumentPartOptions Options { get; private set; }
 
         /// <summary>
         /// Installs a new instance of the command argument part class
@@ -56,18 +48,10 @@ public class CommandArgumentPart
         /// <param name="options">Command argument part options</param>
         public CommandArgumentPart(bool argumentRequired, string argumentExpression, CommandArgumentPartOptions options)
         {
-            // Get a part instance
-            options ??= new CommandArgumentPartOptions();
-            var part = new CommandArgumentPart(argumentRequired, argumentExpression, options.AutoCompleter, options.IsNumeric, options.ExactWording);
-
             // Install some values
             ArgumentRequired = argumentRequired;
             ArgumentExpression = argumentExpression;
-
-            // Install values from the instance
-            AutoCompleter = part.AutoCompleter;
-            IsNumeric = part.IsNumeric;
-            ExactWording = part.ExactWording;
+            Options = options ?? new CommandArgumentPartOptions();
         }
 
         /// <summary>
@@ -78,11 +62,11 @@ public CommandArgumentPart(bool argumentRequired, string argumentExpression, Com
         /// <param name="autoCompleter">Auto completion function</param>
         /// <param name="isNumeric">Specifies whether the argument accepts only numbers (and dots for float values)</param>
         /// <param name="exactWording">User is required to provide this exact wording</param>
-        public CommandArgumentPart(bool argumentRequired, string argumentExpression, Func<string[], string[]> autoCompleter = null, bool isNumeric = false, string[] exactWording = null)
+        /// <param name="argumentDesc">Argument description (unlocalized)</param>
+        public CommandArgumentPart(bool argumentRequired, string argumentExpression, Func<string[], string[]> autoCompleter = null, bool isNumeric = false, string[] exactWording = null, string argumentDesc = "")
         {
             ArgumentRequired = argumentRequired;
             ArgumentExpression = argumentExpression;
-            IsNumeric = isNumeric;
 
             // Check to see if the expression points to a known auto completion function
             if (!string.IsNullOrEmpty(argumentExpression))
@@ -109,8 +93,15 @@ public CommandArgumentPart(bool argumentRequired, string argumentExpression, Fun
                     done = true;
                 }
             }
-            AutoCompleter = autoCompleter;
-            ExactWording = exactWording ?? [];
+
+            // Populate options
+            Options = new CommandArgumentPartOptions()
+            {
+                ArgumentDescription = argumentDesc,
+                AutoCompleter = autoCompleter,
+                ExactWording = exactWording ?? [],
+                IsNumeric = isNumeric,
+            };
         }
 
     }

public/Nitrocid/Shell/ShellBase/Arguments/CommandArgumentPartOptions.cs

@@ -26,7 +26,10 @@ namespace Nitrocid.Shell.ShellBase.Arguments
     /// </summary>
     public class CommandArgumentPartOptions
     {
-
+        /// <summary>
+        /// Argument description
+        /// </summary>
+        public string ArgumentDescription { get; set; }
         /// <summary>
         /// Auto completion function delegate
         /// </summary>
@@ -38,7 +41,7 @@ public class CommandArgumentPartOptions
         /// <summary>
         /// User is required to provide one of the exact wordings
         /// </summary>
-        public string[] ExactWording { get; set; }
+        public string[] ExactWording { get; set; } = [];
 
         /// <summary>
         /// Makes a new instance of the command argument part options

public/Nitrocid/Shell/ShellBase/Arguments/CommandAutoComplete.cs

@@ -110,7 +110,7 @@ internal static string[] GetSuggestions(string text, int index)
                 // There are arguments! Now, check to see if it has the accessible auto completer from the last argument
                 var AutoCompleter =
                     LastArgumentIndex < CommandArgumentInfo.Arguments.Length && LastArgumentIndex >= 0 ?
-                    CommandArgumentInfo.Arguments[LastArgumentIndex].AutoCompleter :
+                    CommandArgumentInfo.Arguments[LastArgumentIndex].Options.AutoCompleter :
                     null;
                 DebugWriter.WriteDebug(DebugLevel.I, "Command {0} has auto complete info? {1}", CommandName, AutoCompleter is not null);
                 if (AutoCompleter is null)

public/Nitrocid/Shell/ShellBase/Help/HelpPrintTools.cs

@@ -261,6 +261,22 @@ internal static void ShowHelpUsage(string command, string commandType)
                     TextWriters.Write(Translate.DoTranslation("Usage:"), false, KernelColorType.ListEntry);
                     TextWriters.Write($" {FinalCommand} {argumentInfo.RenderedUsage}", KernelColorType.ListValue);
 
+                    // If we have arguments, print their descriptions
+                    if (Arguments.Length != 0)
+                    {
+                        TextWriters.Write(Translate.DoTranslation("This command has the below arguments that change how it works:"), KernelColorType.NeutralText);
+                        foreach (var argument in Arguments)
+                        {
+                            string argumentDescUnlocalized = argument.Options.ArgumentDescription;
+                            if (string.IsNullOrWhiteSpace(argument.Options.ArgumentDescription))
+                                argumentDescUnlocalized = /* Localizable */ "Unspecified argument description";
+                            string argumentName = argument.ArgumentExpression;
+                            string argumentDesc = Translate.DoTranslation(argumentDescUnlocalized);
+                            TextWriters.Write($"  {argumentName}: ", false, KernelColorType.ListEntry);
+                            TextWriters.Write(argumentDesc, KernelColorType.ListValue);
+                        }
+                    }
+
                     // If we have switches, print their descriptions
                     if (Switches.Length != 0)
                     {