dotnet-dump command line UX for displaying help could be improved

[MichaelSimons]

Description

The UX around retrieving the command line help isn't documented and could be improved.

Examples using (version '3.1.141901')

1. Running dotnet-dump doesn't give any indication that help can be retrieved for the subcommands.

# dotnet-dump
Required command was not provided.

Usage:
  dotnet-dump [options] [command]

Options:
  --version    Display version information

Commands:
  collect                Capture dumps from a process
  analyze <dump_path>    Starts an interactive shell with debugging commands to explore a dump
  ps                     Lists the dotnet processes that dumps can be collected

# dotnet-dump -h
Usage:
  dotnet-dump [options] [command]

Options:
  --version    Display version information

Commands:
  collect                Capture dumps from a process
  analyze <dump_path>    Starts an interactive shell with debugging commands to explore a dump
  ps                     Lists the dotnet processes that dumps can be collected

I would expect -h|--help to be listed as a supported option. More importantly I would expect there would be an indication of how to retrieve additional help for each of the commands. The options parser doesn't appear to support this format -dotnet-docker -h ps so I would suggest displaying a message for how to retrieve the command help such as Run 'dotnet-dump [Command] --help' for more information on a command.

2. Top level help documentation for analyze is incomplete.

# dotnet-dump -h
Usage:
  dotnet-dump [options] [command]

Options:
  --version    Display version information

Commands:
  collect                Capture dumps from a process
  analyze <dump_path>    Starts an interactive shell with debugging commands to explore a dump
  ps                     Lists the dotnet processes that dumps can be collected

Showing <dump_path> here for the analyze command is strange to me because it feels incomplete because there are other supports args. This is inconsistent with the .NET cli. My suggestion is to just list the commands in the top level help. Require the users to display the analyze help and show them the full cmd syntax.

[mikem8361]

Not showing the help options (#1) and not displaying the full subcommand info (#2) is the current defaults of System.CommandLine package. It will be possible to change, but it may require changing System.CommandLine or duplicating the help builder to add the requested details. I'm not saying won't be done, it may just take more time.

For #2 For the dotnet CLI dotnet --help doesn't display any arguments or [options} for the subcommands so maybe dotnet-dump, etc. (because all of our dotnet global tools have these issues) shouldn't display the <dump_path> on the collect subcommand, etc. But dotnet does display the help option and I definitely agree that it should be displayed by our tools too.

Usage: dotnet [sdk-options] [command] [command-options] [arguments]

Execute a .NET SDK command.

sdk-options:
  -d|--diagnostics  Enable diagnostic output.
  -h|--help         Show command line help.
  --info            Display .NET information.
  --list-runtimes   Display the installed runtimes.
  --list-sdks       Display the installed SDKs.
  --version         Display .NET SDK version in use.

SDK commands:
  add               Add a package or reference to a .NET project.
  build             Build a .NET project.
  build-server      Interact with servers started by a build.
  clean             Clean build outputs of a .NET project.
  help              Show command line help.
  list              List project references of a .NET project.
  msbuild           Run Microsoft Build Engine (MSBuild) commands.
  new               Create a new .NET project or file.
...

[MichaelSimons]

I should have included an example of what I thought would be ideal. This mimics dotnet as @mikem8361 showed.

# dotnet-dump -h
Usage:
  dotnet-dump [options] [command] [command-options] [arguments]

Options:
 -h|--help     Show command line help.
  --version    Display version information

Commands:
  collect                Capture dumps from a process
  analyze                Starts an interactive shell with debugging commands to explore a dump
  ps                     Lists the dotnet processes that dumps can be collected

Run 'dotnet-dump [command] --help' for more information on a command.

There are 4 differences.

1. -h|--help is included in the top level options
2. <dump_path> is removed from the analyze command in the top level help.
3. Run 'dotnet-dump [command] --help' for more information on a command. is added at the bottom of the top level help.
4. [command-options] [arguments] are added to the Usage in the top level help.