How to force long help output

[dfego]

I'm working on an interface that has an array of strings. After a lot of poking around, I've settled on:

#[arg(short, value_parser = VERSIONS)]

I've noticed that if I were to use an enum for this and docstring (e.g. ///) at least one of the values, I get a longer option when I --help that separates out each string into its own line. I found the relevant code here:

clap/clap_builder/src/output/help_template.rs

Line 675 in fc55ad0

self.writer.push_str("Possible values:");

I'd like to force this behavior, rather than having the values compacted onto one line or forcing in comments I otherwise wouldn't need. Is this possible?

To be clear, what I want looks like:

Possible values:
- one
- two
- three

rather than:

[possible values: one, two, three]

From what I can tell, this specific behavior is independent of -h vs --help. In fact, I can actually get my entire help to be long by using:

#[arg(short, value_parser = VERSIONS, long_help ="")]

But that doesn't end up creating a list, but does change the format of the rest of the help.

[epage]

To use long help, we need two things

For it to be requested (--help by default, you can provide your own flag with the long-help action to make it always requested)

clap/clap_builder/src/builder/command.rs

Line 5047 in fc55ad0

use_long = use_long && self.long_help_exists();

Long help content to be present

clap/clap_builder/src/builder/command.rs

Lines 5083 to 5088 in fc55ad0

	// Subcommands aren't checked because we prefer short help for them, deferring to
	// `cmd subcmd --help` for more.
	self.get_long_about().is_some()
	|| self.get_before_long_help().is_some()
	|| self.get_after_long_help().is_some()
	|| self.get_arguments().any(should_long)

clap/clap_builder/src/builder/command.rs

Lines 5068 to 5081 in fc55ad0

	// In this case, both must be checked. This allows the retention of
	// original formatting, but also ensures that the actual -h or --help
	// specified by the user is sent through. If hide_short_help is not included,
	// then items specified with hidden_short_help will also be hidden.
	let should_long = |v: &Arg| {
	!v.is_hide_set()
	&& (v.get_long_help().is_some()
	|| v.is_hide_long_help_set()
	|| v.is_hide_short_help_set()
	|| (!v.is_hide_possible_values_set()
	&& v.get_possible_values()
	.iter()
	.any(PossibleValue::should_show_help)))
	};

doc strings are split on the first empty line. If there is anything after the split, it is put in the long help for that argument.

When long help is being used, possible-values show the long form if any has documentation

clap/clap_builder/src/output/help_template.rs

Lines 840 to 846 in fc55ad0

	fn use_long_pv(&self, arg: &Arg) -> bool {
	self.use_long
	&& arg
	.get_possible_values()
	.iter()
	.any(PossibleValue::should_show_help)
	}

clap/clap_builder/src/builder/possible_value.rs

Lines 180 to 182 in fc55ad0

	pub(crate) fn should_show_help(&self) -> bool {
	!self.hide && self.help.is_some()
	}

So to see long help for possible values, you need

• long help
• a long description on the command or an argument
• a description on a value

We do not offer a way to force possible values to show in the long form otherwise. The assumption being that it is taking a lot of vertical space, which is limited in CLIs.