Command examples

[Tyrrrz]

Discussed in #114

^{Originally posted by wayneyaoo December 4, 2021}
Can we have concept of "Example" for each command that can be specified by the CLI author and a new section is rendered as "EXAMPLE".

I was imaging something like

[Command("verb")]
public class MyCommand : ICommand
{
    // options and parameters go here as property

    [Example]
    public (static) Example[] Examples = new [] 
        { new Example("verb --option value"), new Example("verb --anotherPositionalOption") };
}

and the examples could be rendered to another section like "EXAMPLE" when ./myapp verb -h is called.

I'm happy to contribute if this looks good. Or we can discuss.

[Tyrrrz]

My reply: #114 (comment)

[Tyrrrz]

Note: this is better implemented as another string property on the CommandAttribute, not as a type member as visualized in the original post.

[Tyrrrz]

Example usage:

[Command("foo", Examples = new[]
	{
		// Note: no need to add the command name here
		"--bar 42",
		"-b 42"
	}
]
public class MyCommand : ICommand
{
	// ...
}

The examples would then be shown in the "usage" section of the help text:

USAGE
  dotnet myapp.dll foo [options]
  dotnet myapp.dll foo --bar 42
  dotnet myapp.dll foo -b 42

OPTIONS
  -b|--bar          Something.
  -h|--help         Shows help text.