Detailed help for ValueEnum variants

[epage]

Discussed in #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

clap/clap_derive/src/item.rs

Lines 173 to 197 in 0096ace

	pub(crate) fn from_value_enum_variant(
	variant: &Variant,
	argument_casing: Sp<CasingStyle>,
	env_casing: Sp<CasingStyle>,
	) -> Result<Self, syn::Error> {
	let ident = variant.ident.clone();
	let span = variant.span();
	let kind = Sp::new(Kind::Value, span);
	let mut res = Self::new(
	Name::Derived(variant.ident.clone()),
	ident,
	None,
	argument_casing,
	env_casing,
	kind,
	);
	let parsed_attrs = ClapAttr::parse_all(&variant.attrs)?;
	res.infer_kind(&parsed_attrs)?;
	res.push_attrs(&parsed_attrs)?;
	if matches!(&*res.kind, Kind::Value) {
	res.push_doc_comment(&variant.attrs, "help", None);
	}
	Ok(res)
	}

.

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.