Detailed help for ValueEnum variants

[timmc]

I have a ValueEnum with variants that have detailed help (that is, more than one paragraph of doc comments). How can I get clap to show this when --help is invoked?

Example using clap 4.5.1:

use clap::{Parser, ValueEnum};

#[derive(Clone, Debug, ValueEnum)]
enum Multi {
    /// Foo short help.
    ///
    /// Foo detailed help. This should be exposed in --help.
    Foo,
    /// Bar short help.
    ///
    /// Bar detailed help. This should be exposed in --help.
    Bar,
}

#[derive(Clone, Debug, Parser)]
struct Cli {
    myopt: Multi,
}

pub fn main() {
    Cli::parse();
}

Output from --help:

Usage: clap_demo <MYOPT>

Arguments:
  <MYOPT>
          Possible values:
          - foo: Foo short help
          - bar: Bar short help

Options:
  -h, --help
          Print help (see a summary with '-h')

I'd like some way of exposing the full docstring of Foo and Bar in the myopt help string.

[konstin]

We have a similar problem: We were documenting a caveat with a value enum in the doc comment of its variant (astral-sh/uv@5d37c7e/crates/uv-install-wheel/src/linker.rs#L18-L36). We now realized that the only the first line of the doc comment is captured (astral-sh/uv#15115), and the rest does not get preserved. Is that intentional, or could we add long help and capture that too?

[epage]

At this time, there is only one form of about for a PossibleValue

• In short help, we show nothing
• In long help, we show about

So the question is whether we should be pulling the synopsis or full doc comment. This was implemented in #2762 to fix #2731.

A quick look over #2731 and #2762 and I'm not finding this explicitly discussed why we made the decision we did. @ModProg do you remember?

Potential guesses

• Looking over Support about for possible_values e.g. ArgEnum #2731, the focus was on shell completions which is better suited for a synopsis.
• Knowing the code, we do automatically map the doc comment synopsis to about which actually broke things when we generated long_about calls (fix ArgEnum multiline doc comment #2916), so I could see this fall out of the implementation.

If we changed this, it would likely be a breaking change and wait until 5.0.0 (or be put behind unstable-v5 feature flag) because we'd start to show in --help content people may have intended to not be there.

[ModProg]

I don't think we actively decided this, I think we only tested with single line doc comments so didn't notice until #2916.

I think it does make sense to show the "long about" with --help as usually you won't add doc comments there which you don't want to show in the help message.

[epage]

I went ahead and converted this Discussion into an Issue (#6096)