Confusing usage of angle and square brackets in the inline and online documentation

[BrightSoul]

I'm using the .NET SDK v.2.0.2. The inline command guide is displaying very confusing conventions for optional and mandatory arguments. For instance, let's take the output from the dotnet sln command when it's run from a directory that does not contain a solution.

C:\>dotnet sln
Required command was not provided.
Usage: dotnet sln [options] <SLN_FILE> [command]
Arguments:
  <SLN_FILE>   Solution file to operate on. If not specified, the command will search the current directory for one.

Options:
  -h, --help   Show help information.

Commands:
  add <args>      .NET Add project(s) to a solution file Command
  list            .NET List project(s) in a solution file Command
  remove <args>   .NET Remove project(s) from a solution file Command

Let's take a look at the usage example, in particular: Usage: dotnet sln [options] <SLN_FILE> [command]

If we follow these conventions which are widely spread among *nix users and developers, we interpret the usage example as having a mandatory SLN_FILE argument, since it's enclosed in angle brackets. But, actually, it's not mandatory as explained a couple of lines below: Solution file to operate on. **If not specified**, the command will search the current directory for one. Since it's an optional argument, it should be enclosed in square brackets. Also, there's a command argument which is mandatory, but it's instead enclosed in square brackets which is the convention for optional arguments.

To add even more confusion, the online documentation for the dotnet sln command reports some usage examples like this: dotnet sln [<SOLUTION_NAME>] add <PROJECT> <PROJECT> ... The SOLUTION_NAME argument has now a different name (it was SLN_FILE in the inline guide) and it's enclosed by both square and angle brackets.

Moderator Mairacw from the online docs kindly explained that:

The angle bracket is to indicate this is an argument (vs. an option like -h).

But... what's the actual need for differentiating between arguments and options? And why did you choose to stray from the existing conventions?

Moreno

[wli3]

Hi Moreno,

We do try to stay with existing convention. However, in this case I think this is more of a technical problem. The help is generated from the parser itself, so it is in sync with actual behavior. However, I think in this case .DefaultToCurrentDirectory() is not properly modeled. The help view should reflect that it is optional instead of Accept.ExactlyOneArgument()

https://github.com/dotnet/cli/blob/0eff67d20768cff90eb125ff0e16e52cfc40ced6/src/dotnet/commands/dotnet-sln/SlnCommandParser.cs#L10-L24