Improve documentation for clap::Args::augment_args and clap::Args::augment_args_for_update

[nwalfield]

Please complete the following tasks

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

Rust Version

rustc 1.75.0 (82e1608df 2023-12-21)

Clap Version

4.4.18

Minimal reproducible code

Read the documentation for clap::Args:

fn augment_args(cmd: Command) -> Command`

Append to Command so it can instantiate Self.

See also CommandFactory.
source

fn augment_args_for_update(cmd: Command) -> Command`

Append to Command so it can update self.

This is used to implement #[command(flatten)]

See also CommandFactory.

The documentation does not describe how to implement Args::augment_args or Args::augment_args_for_update, and it only hints at the difference between them. The documentation links to CommandFactory, but that doesn't really help either. The flatten_hand_args.rs example provides a basic idea, but I still have to guess at the semantics. Further, the example's implementation of augment_args and augment_args_for_update are identical, which is baffling. I tried reading the source code, but still couldn't figure out the difference between the two.

Steps to reproduce the bug with the above code

Read the above documentation.

Actual Behaviour

The current documentation is missing details. The example is good, but incomplete.

Expected Behaviour

The documentation should describe the semantics of the two methods. It should also make clearer what the difference between the two is (what does so it can instantiate Self vs so it can update Self mean).

Additional Context

This seemed like the most appropriate template for this documentation issue. I apologize if I should have chosen a different template.

Debug Output

No response

[epage]

5488bcf, df165a2, a3a4764 tweaked the wording.

Whether the update calls need any different logic is dependent on the situation. The main situation I can remember when polishing it up for release was that there are no required arguments.

Overall, update adds a lot of complexity for a very small number of users that I am tempted to just remove it (#4974).