Description strings for subcommands

[suntong]

A descriptive message can be added at the top of the help text by implementing a Description function that returns a string.

./s-subcommands -h
this program does this and that
Usage: s-subcommands [--quiet] <command> [<args>]

Options:
  --quiet, -q
  --help, -h             display this help and exit

Commands:
  checkout
  commit
  push

Besides giving a descriptive message to the main program, please consider adding them for subcommands as well, like git:

   clone             Clone a repository into a new directory
   init              Create an empty Git repository or reinitialize an existing one

and use it for subcommand helps as well:

I.e., instead of:

 ./s-subcommands commit -h
this program does this and that
Usage: s-subcommands commit [--all] [--message MESSAGE]

Options:
  --all, -a
  --message MESSAGE, -m MESSAGE

Global options:
  --quiet, -q
  --help, -h             display this help and exit

The first line better be

commit - Record changes to the repository

[alexflint]

Yeah, seems reasonable. Happy to implement this.

[alexflint]

Well ok the reason for this is that subcommands are nil pointers when the help string for the parent command is being printed. I didn't want to assume that you could safely call Description() on a nil struct. I think most implementations of Description() just return a static string, or at least do not access the receiver struct, but still some users might be confused by having Description() invoked with a nil receiver.

The way to get the output you want, though will in involve repetition in your code, is to add a help tag to the subcommand like this:

var args struct {
  Commit *commitCmd `arg:"subcommand" help:"Record changes to the repository"`
}

I'm still open to implementing this, just considering options carefully.

[suntong]

Yeah, sure that'd do as well -- simpler=better.

Just that, when running ./s-subcommands commit -h, the first line is still

this program does this and that

but I think the first line better be:

commit - Record changes to the repository