Templating: Default Value in CLI Showing Incorrectly

[RehanSaeed]

I have the specified custom symbol:

    "StyleCop": {
      "type": "parameter",
      "datatype": "bool",
      "description": "Adds and enforces StyleCop analysers. NOTE: You may need to sort using statements if you enable this due to limitations in the dotnet new templating engine.",
      "defaultValue": "false"
    },

However, when I check the help menu in the CLI using dotnet new api --help, I see that it looks like the default is true because it has a star beside it.

This was reported to me as a bug in https://github.com/Dotnet-Boxed/Templates/issues/758.

[donJoseLuis]

@AR-May please take a look. Is this something we have availability for this week or should we include it in our road map & backlog?

[AR-May]

Hello @RehanSaeed! Here is an example of the same situation:

Options:
-p|--parameter
bool - Optional
Default: false / (*) true

* Indicates the value used if the switch is provided without a value.

Note the last line there, explaining the meaning of the star. The value shows correctly. We do have two different defaults. Let's write down all the use cases:

1. We may not use --parameter.
2. We may use --parameter without any value.
3. We may use --parameter value or --parameter=value.

The first one (false) is the default value for case 1 and the second one, with a star, is the default value for case 2.

[AR-May]

However, I do see that this presentation of defaults could be a bit confusing if you have a large list of template parameters.
I'll ask PM and we will see should something to be done on the matter of presentation.

[KathleenDollard]

These having different defaults feels wrong:

1. We may not use --parameter.
2. We may use --parameter without any value.

Let's get Posix experts to weigh in on how common this is in the non-Windows world. From a Windows world, this made me cry.

I'd like to put this on the backlog for 5.0.200 so we have time to think through the behavior and how we want to express this.

@jonsequitur

[jonsequitur]

It took me a couple of reads through the help text before I realized it's describing the usual flag options (i.e. booleans) used in GNU/POSIX command lines as well as Windows. Flag options are common enough that they're intuitive, and not mentioning that they'll accept an argument (e.g. --parameter=true) is more standard. Explaining that it _can_ accept an argument draws attention to a detail that creates a bit of information overload, I think.

[KathleenDollard]

In looking at this again and with @jonsequitur 's comments, I see that it is normal behavior for a switch, so this should basically occur all the time. That doesn't mean it's what users expect. I want us to look at this super verbose help as part of a larger look at templates after we have the new parser. But for now, let's just make it a bit more verbose:

Default: false if the option is not included

[AR-May]

Hello @jonsequitur, @KathleenDollard!
@grinrag could you please also join our conversation.

Yes, for boolean parameters it is clear enough that if you provide a parameter without a value, the value should be "true". So, there is no need to provide information about default if a parameter is provided without a value. However, for all other types of parameters, it is not like that.

I was looking at the code and it turns out, that not only for boolean parameters there may be two different defaults. There is an undocumented feature that allows us to provide two defaults: "defaultValue" and "DefaultIfOptionWithoutValue", which may be different. You could see the test with an example of such a template here.

I checked that one can use a non-boolean option without a value when creating a template. So, it turns out that we are not speaking only about flag options.

[AR-May]

As was agreed with PM, I fixed the help message such that for normal behavior of the boolean switch no unnecessary/confusing information is shown. If and only if the "default if the option is without value" is unusual, the more verbose message will be shown.