Show ArgumentHelpName in help if explicitly set by user (#1367)

* Show ArgumentHelpName in help if explicitly set by user

* Add HelpName field to Argument

Author: sfoslund

src/System.CommandLine.Tests/Help/HelpBuilderTests.Approval.cs

@@ -52,12 +52,10 @@ public void Help_describes_default_values_for_complex_root_command_scenario()
                 new Option<FileAccess>(aliases: new string[] {"--the-root-option-enum-arg", "-troea"}, () => FileAccess.Read) 
                 {
                     Description = "the-root-option-description",
-                    ArgumentHelpName = "the-root-option-arg",
                 },
                 new Option<FileAccess>(aliases: new string[] {"--the-root-option-required-enum-arg", "-trorea"}, () => FileAccess.Read) 
                 {
                     Description = "the-root-option-description",
-                    ArgumentHelpName = "the-root-option-arg",
                     IsRequired = true
                 },
                 new Option(aliases: new string[] {"--the-root-option-multi-line-description", "-tromld"}) {

src/System.CommandLine.Tests/Help/HelpBuilderTests.cs

@@ -467,6 +467,32 @@ public void Arguments_section_includes_configured_argument_aliases()
             help.Should().Contain("Sets the verbosity.");
         }
 
+
+        private enum VerbosityOptions
+        {
+            q,
+            m,
+            n,
+            d,
+        }
+
+        [Fact]
+        public void Arguments_section_uses_name_over_suggestions_if_specified()
+        {
+            var command = new Command("the-command")
+            {
+                new Option<VerbosityOptions>(new[] { "-v", "--verbosity" })
+                {
+                    ArgumentHelpName = "LEVEL"
+                }
+            };
+
+            _helpBuilder.Write(command);
+
+            var help = _console.Out.ToString();
+            help.Should().Contain("-v, --verbosity <LEVEL>");
+        }
+
         [Fact]
         public void Arguments_section_uses_description_if_provided()
         {
@@ -1238,7 +1264,7 @@ public void Help_describes_default_value_for_option_with_argument_having_default
 
             help.Should().Contain($"[default: the-arg-value]");
         }
-
+        
         [Fact]
         public void Option_arguments_with_default_values_that_are_enumerable_display_pipe_delimited_list()
         {

src/System.CommandLine.Tests/OptionTests.cs

@@ -240,7 +240,7 @@ public void Argument_takes_option_alias_as_its_name_when_it_is_not_provided()
         {
             var command = new Option("--alias", arity: ArgumentArity.ZeroOrOne);
 
-            command.ArgumentHelpName.Should().Be("alias");
+            command.Name.Should().Be("alias");
         }
 
         [Fact]

src/System.CommandLine/Argument.cs

@@ -65,6 +65,11 @@ public IArgumentArity? Arity
             set => _arity = value;
         }
 
+        /// <summary>
+        /// Argument help name
+        /// </summary>
+        internal string? HelpName { get; set; }
+
         internal TryConvertArgument? ConvertArguments
         {
             get

src/System.CommandLine/Help/HelpBuilder.cs

@@ -522,7 +522,12 @@ protected string GetArgumentDescriptor(IArgument argument)
 
             string descriptor;
             var suggestions = argument.GetSuggestions().ToArray();
-            if (suggestions.Length > 0)
+            var helpName = GetArgumentHelpName(argument);
+            if (!string.IsNullOrEmpty(helpName))
+            {
+                descriptor = helpName!;
+            }
+            else if (suggestions.Length > 0)
             {
                 descriptor = string.Join("|", suggestions);
             }
@@ -538,6 +543,12 @@ protected string GetArgumentDescriptor(IArgument argument)
             return descriptor;
         }
 
+        private string? GetArgumentHelpName(IArgument argument)
+        {
+            var arg = argument as Argument;
+            return arg?.HelpName;
+        }
+
         private class Customization
         {
             public Customization(Func<string?>? getDescriptor,

src/System.CommandLine/Option.cs

@@ -131,10 +131,13 @@ internal virtual Argument Argument
         /// <value>
         /// The name of the argument when displayed in help.
         /// </value>
-        public string ArgumentHelpName
+        public string? ArgumentHelpName
         {
-            get => Argument.Name;
-            set => Argument.Name = value;
+            get => Argument.HelpName;
+            set
+            {
+                Argument.HelpName = value;
+            }
         }
 
         /// <summary>