ArgEnum: Derive long help from variant doc comments

[FlorianKohn]

Hi all,

I was wondering whether it is (or should be) possible to derive a long help message from the doc comments of an enum. The use-case would for example be a verbosity argument:

  #[derive(Clone, Debug, Parser)]
  #[clap(author, version, about, long_about = None)]
  struct Cli {
      /// Sets the verbosity of the program
      #[clap(arg_enum)]
      verbosity: Option<Verbosity>,
  }
  
  #[derive(Clone, Debug, ArgEnum)]
  enum Verbosity {
      /// Display no info
      Silent,
      /// Display errors only
      Error,
      /// Display warnings and errors
      Warning,
      /// Display everything
      Debug,
  }

The short help would then output something like:

USAGE:
    test [VERBOSITY]

ARGS:
    <VERBOSITY>    Sets the verbosity of the program [possible values: silent, error, warning,
                   debug]

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

And the derived long help would look like this:

USAGE:
    test [VERBOSITY]

ARGS:
    <VERBOSITY>
            Sets the verbosity of the program

            possible values:
                silent:      Display no help
                error:       Display errors only
                warning:     Display warnings and errors
                debug:       Display everything

OPTIONS:
    -h, --help
            Print help information

    -V, --version
            Print version information

[epage]

We do collect the doc comments but only show them in completion scripts for now. We have #3312 but the main question is what level of notice this change requires because we'll start showing help that might not have been written for users (breaking change, a minor release with a compatibility note, etc).