Detailed help for ValueEnum variants

[epage]

Discussed in https://github.com/clap-rs/clap/discussions/6070

^{Originally posted by timmc July 13, 2025} 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.

[epage]

Based on the Discussion, it looks like this is a happenstance of implementation so we're fine with changing this.

However, if we did this now, we could start showing content people did not intend to be shown, making this a breaking change.

If someone wants to contribute this before v5.0.0, they could put it behind the unstable-v5 feature flag.

[smoqadam]

hey @epage, I’d like to work on this issue as my first contribution to clap. Could you point me to where in the codebase I should start and any tests/examples to check? I’ll open a draft PR and adjust based on feedback.

[epage]

ValueEnum variant processing starts at https://github.com/clap-rs/clap/blob/0096ace8b15b20a77e71806eab4c8df10cae278c/clap_derive/src/item.rs#L173-L197.

I believe we should already have tests in tests/derive that are relevant (they ignore the long help content).

[epage]

And as noted, to implement this now, it needs to be behind the unstable-v5 feature flag.