Document how to use ArgGroups from derive API

[kpreid]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

4.4.7

Describe your use case

Context:

• I want to make a set of mutually exclusive options
• I understand that ArgGroups serve this purpose
• I am using derive(clap::Parser)

Problem:

The documentation does not contain any examples how to achieve this or describe the full picture. The only discussion of is the "ArgGroup Attributes" which mentions in passing that "These correspond to the ArgGroup which is implicitly created for each Args derive.", from which I can infer that the solution is likely to create a nested struct for the group (and I later determined this succeeded).

I tried #[arg(group = "action", conflicts_with = "action")] on each arg to see if that worked, but (not too surprisingly) it made the args conflict with themselves.

Describe the solution you'd like

• Provide at least one discoverable example of using ArgGroup features such as mutual exclusion in a derive-only program.
• Clarify in reference documentation that in order to make a configured group via derive, you must make a derive(Parser) struct for that group.

Alternatives, if applicable

No response

Additional Context

No response

[kpreid]

Also, the ArgGroup documentation says that multiple = false is the default, but the derive(Parser) implicit group defaults to multiple = true and the derive reference does not mention this.

[epage]

A part of the tutorial does cover mutually exclusive arg group.

#5200 documents the implicit behavior.

Ideally we'd have #2621 which would make this more natural.

[kpreid]

A part of the tutorial does cover mutually exclusive arg group.

Ah. To give more detail: only when writing up this issue did I discover that the tutorial even had multiple chapters, and while I did skim through them I didn't search every chapter thoroughly (and to my thought process, "validation" meant "of values", not "of all states args can be in"). And, when I'm trying to solve a problem, I generally don't go for tutorials first, but for API-documentation (in the sense of the kind of thing rustdoc is mainly used for).

I still think that it would be an improvement if searching the derive reference page for “ArgGroup” turned up a sentence that communicated that the only way to create groups, that have nondefault options and don't contain every arg, is with a separate struct.

[epage]

Ah. To give more detail: only when writing up this issue did I discover that the tutorial even had multiple chapters, and while I did skim through them I didn't search every chapter thoroughly (and to my thought process, "validation" meant "of values", not "of all states args can be in").

It was originally all in one page and people were overwhelmed by it and complaining. #5163 is about starting it on the table of contents rather than the first page.

I still think that it would be an improvement if searching the derive reference page for “ArgGroup” turned up a sentence that communicated that the only way to create groups, that have nondefault options and don't contain every arg, is with a separate struct.

You can always create a group manually (#[command(group = ArgGroup::new(...)...)]). That is covered by explaining raw attributes and linking to the API.

In the overview, we do show a separate struct with #[group] attributes.

When discussing ArgGroup, we do have this

These correspond to the ArgGroup which is implicitly created for each Args derive.

Maybe examples would help? I don't want to commit to examples for everything (see #4090). Maybe linking to a part in the tutorial that is most relevant for each type of attribute?

[kpreid]

I think an example would help (and I'd justify writing one with "groups are not just a single option but an entire kind of entity"), and cross-references to the tutorial would help.

[epage]

#5229 adds links for each attribute type to the relevant tutorial sections.