Bool arguments missing name in help page

[skrysmanski]

Consider this application:

static int Main(string[] args)
{
    var rootCommand = new RootCommand
    {
        new Argument<bool>("value1", "Some value"),
        new Argument<int>("value2", "Another value"),
    };

    rootCommand.Handler = CommandHandler.Create<bool>(value1 =>
    {
        Console.WriteLine($"The value for 'value1' is: {value1}");
    });

    return rootCommand.Invoke(args);
}

When calling this application with the --help parameter, we get an output like this:

Usage:
  CommandLineReproducer [options] [<value1> <value2>]

Arguments:
              Some value
  <value2>    Another value

Options:
  --version         Show version information
  -?, -h, --help    Show help and usage information

Notice how in the Arguments sections we see <value2> but not <value1>. It seems it's not printed here because the type parameter is bool.

[adamhewitt627]

I tracked this down to #500, and more specifically:

command-line-api/src/System.CommandLine/Help/HelpBuilder.cs

Lines 529 to 533 in 4b43131

	if (argument.ValueType == typeof(bool) ||
	argument.ValueType == typeof(bool?))
	{
	return "";
	}

It looks like that change might be intended for when the Argument is on an Option, while this issue puts it on the root directly and probably should have the <value1> included? Or, should it have <true|false>?

[Pxtl]

The documentation doesn't seem to discuss positional arguments at all, I only found out about them when exploring the source... are they getting deprecated in favour of a flag on options or something similar?

It took me a long time to figure out they even existed because I'm coming to this from PowerShell where an "argument" is just an "option" with an index so it its name is specified optionally, like in C# with the optional parameters.

[jonsequitur]

They're not getting deprecated. It sounds like we need to clarify this.

I think the documentation doesn't call them out as "positional" because all arguments are positional in System.CommandLine.

An option argument (part of an Option) must always follow an option token:

> myapp --verbose 123
                  ^-^
                  Option argument

A command argument is also positional but only relative to other command arguments, not to options.

So given either of these command definitions:

new RootCommand
{ 
    new Option<bool>("--verbose"),
    new Argument<int>(), 
    new Argument<string>()
}

or

new RootCommand
{ 
    new Argument<int>(), 
    new Argument<string>(),
    new Option<bool>("--verbose")
}

, the following two command lines are equivalent:

> myapp --verbose arg1 arg2 arg3
                  ^------------^
                  Command arguments

> myapp arg1 arg2 arg3 --verbose 
        ^------------^
         Command arguments

Thoughts?

[Pxtl]

Okay, I think I get it now - I'm just coming from mentally looking at this as like C# method calls and PowerShell cmdlets, both cases where the partition between "arguments" and "options" aren't as firm.