For #4812, we are looking at including it within the example usage. I'd be interested in exploring ways of doing that here as well.

Placing it in the usage can be similar to what was done for #1052, but then that's only visible when there's more than one value name.

I'm proposing to also add it in the help message of the option/argument

that's only visible when there's more than one value name.

Not quite as that is conflating a couple of features which I realized in seeing #5817

In that PR,

            arg!(-f --fake <s> "some help")
                .required(true)
                .required(true)
                .value_names(["some", "val"])
                .action(ArgAction::Set)
                .value_delimiter(':'),
        )

gets rendered as

Usage: test [OPTIONS] --fake <some>:<val> --birthday-song <song> --birthday-song-volume <volume>

Options:
  -f, --fake <some>:<val>  some help [value delimiter: ':']

Seeing that is reminding of the weird interplay of

• value_names
• num_args: gets defaulted by value_names
• value_delimiter

So --fake actually accepts --fake some1:some2:some3 val1:val2:val3. This was likely not intended for that test but slipped through the cracks as features changed through v3. The test was likely trying to get --fake some:val but now we only support unbounded value delimiters.

We have the idea of extra_values

If we used something like that, we could get

  -f, --fake <some>:... <val>:...  some help [value delimiter: ':']

or

  -f, --fake <some>[:...] <val>[:...]  some help [value delimiter: ':']

I'm proposing to also add it in the help message of the option/argument

Currently we do this for

• default values
• env
• possible values (Show the type of arguments in help message? #5156 could alleviate this in some cases)

Seeing two of those rendered together, we get

Usage: default [OPTIONS]

Options:
      --arg <argument>  Pass an argument to the program. [default: "\n"] [possible values: normal, "
                        ", "\n", "\t", other]
  -h, --help            Print help
  -V, --version         Print version

Overall, I'm not thrilled with these and don't feel like they compose well together, and worry about extending them more. Also, if we can find ways to include them in the usage, it becomes more natural (like I want to do with possible values).

btw a good test case for one, the other, or both options is to see what Cargo's output would look like with changing this.

So --fake actually accepts --fake some1:some2:some3 val1:val2:val3. This was likely not intended for that test but slipped through the cracks as features changed through v3. The test was likely trying to get --fake some:val but now we only support unbounded value delimiters.

From what I gathered, there used to be an option to require the delimiter, but without it we're left with allowing both the delimiter and the space separated values. I didn't think that an issue.

Your idea with the extra_values sounds great, and we could even indicate the delimiter as optional with something like:

  -f, --fake <some>[ : | ' ' ]... <val>[ : | ' ' ]...  some help

Although it gets a bit hard to read...

  -f, --fake <some>[[ : | ' ' ]...]

About the [help message] part, if it doesn't impact the direct usage (like a default value), then it could only be display in the long--help version to remove?

btw a good test case for one, the other, or both options is to see what Cargo's output would look like with changing this.

Any particular cargo command I can try to see interesting result?

From what I gathered, there used to be an option to require the delimiter, but without it we're left with allowing both the delimiter and the space separated values. I didn't think that an issue.

That setting was because of a weird interaction between features and became redundant. Just setting a value delimiter makes it so you only use the value delimiter. You have to explicitly opt-in to num_args)1..) or similar to have them both active.

-f, --fake <some>[ : | ' ' ]... <val>[ : | ' ' ]... some help

If you have both num_args(1..) and value_delimiter(':'), I'm not sure how the value_names should be integrated in, whether they should be shown as part of the first std::env::args_os entry (kind of like you showed though yours is also interleaved) or one value_name per entry (like what I showed)

Any particular cargo command I can try to see interesting result?

Hmm, the only delimited value I'm remember is --features and we hand-implement that because we have two delimiters. If we had it showing in the usage, I'd change it so one of the two was done through clap so it would be rendered.