Allow API users to deprecate args

[valadaptive]

Please complete the following tasks

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

Clap Version

4.5.4

Describe your use case

This seems to be a prerequisite to rust-lang/cargo#6790, or at the very least it would really help.

To stabilize Cargo's --out-dir flag, it likely will need to be renamed to something else. However, there are a lot of users of --out-dir, so it would be nice to be able to deprecate --out-dir and direct users to whatever it gets renamed to.

Such a scenario is applicable to other projects as well: API consumers may want to rename arguments or give them a deprecation period before removing them entirely.

Describe the solution you'd like

A way to mark Args as deprecated, or warn when they are passed. Passing such an argument to the program will result in a warning being printed, telling the user to either stop using the argument or migrate to its replacement.

I don't entirely know what this API should look like--should it be a generic "warn on argument use" API or specifically designed around deprecation?

Alternatives, if applicable

1. A way to specifically mark Args as deprecated, possibly allowing for deprecation-specific functionality like automatically redirecting users to their replacements.
2. A simpler "print a warning when argument passed" mechanism.

Additional Context

No response

[epage]

Closing in favor of #3321. If there is a reason to keep this open separately, let us know!

As for cargo, I wouldn't wait on anything like this. We've already handled cases like this before by defining both attributes and suing shell.warn if the deprecated one is used.