docs: Clarify deprecations

This commit is contained in:
Ed Page 2021-12-08 11:11:26 -06:00
parent 0cc5369e97
commit e5997c1001
6 changed files with 20 additions and 17 deletions

View file

@ -34,6 +34,16 @@ You can now override the default group with `Arg::help_heading` and
`App::subcommand_help_heading`. To apply a heading to a series of arguments,
you can set `App::help_heading`.
**Deprecations**
While a lot of deprecations have been added to clean up the API (overloaded
meaning of `Arg::multiple`) or make things more consistent, some particular
highlights are:
- `clap_app!` has been deprecated in favor of the builder API with `arg!` ([clap-rs/clap#2835](https://github.com/clap-rs/clap/issues/2835))
- `Arg::from_usage` has been deprecated in favor of `arg!` ([clap-rs/clap#3087](https://github.com/clap-rs/clap/issues/3087))
- [Porting example](https://github.com/clap-rs/clap/commit/4c4a2b86a08ef9e2d63010aab4909dd5a013dfb0)
- The YAML API has been deprecated in favor the builder or derive APIs ([clap-rs/clap#3087](https://github.com/clap-rs/clap/issues/3087))
### Migrating
**From clap v2**
@ -178,13 +188,6 @@ Easier to catch changes:
On top of the clap 2 changes
### Deprecations
While a lot of deprecations have been added to clean up the API (overloaded meaning of `Arg::multiple`) or make things more consistent, some particular highlights are:
- `clap_app!` has been deprecated in favor of the builder API with `arg!` ([clap-rs/clap#2835](https://github.com/clap-rs/clap/issues/2835))
- `Arg::from_usage` has been deprecated in favor of `arg!`
- The YAML API has been deprecated in favor the builder or derive APIs
### Performance
**From clap 2**

View file

@ -2327,7 +2327,7 @@ impl<'help> App<'help> {
/// Deprecated
impl<'help> App<'help> {
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[deprecated(
since = "3.0.0",
@ -2494,14 +2494,14 @@ impl<'help> App<'help> {
self.term_width(width)
}
/// Deprecated in [Issue #8](https://github.com/epage/clapng/issues/8), see [`arg!`][crate::arg!].
/// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
#[deprecated(since = "3.0.0", note = "Replaced with `arg!`")]
pub fn arg_from_usage(self, usage: &'help str) -> Self {
#![allow(deprecated)]
self.arg(Arg::from_usage(usage))
}
/// Deprecated in [Issue #8](https://github.com/epage/clapng/issues/8), see [`arg!`][crate::arg!].
/// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
#[deprecated(since = "3.0.0", note = "Replaced with `arg!`")]
pub fn args_from_usage(mut self, usage: &'help str) -> Self {
#![allow(deprecated)]

View file

@ -4603,7 +4603,7 @@ impl<'help> Arg<'help> {
Self::new(n)
}
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[deprecated(
since = "3.0.0",
@ -4676,7 +4676,7 @@ impl<'help> Arg<'help> {
a
}
/// Deprecated in [Issue #8](https://github.com/epage/clapng/issues/8), see [`arg!`][crate::arg!].
/// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
#[deprecated(since = "3.0.0", note = "Replaced with `arg!`")]
pub fn from_usage(u: &'help str) -> Self {
UsageParser::from_usage(u).parse()

View file

@ -438,7 +438,7 @@ impl<'help> ArgGroup<'help> {
Self::new(n)
}
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[deprecated(
since = "3.0.0",
@ -463,10 +463,10 @@ impl<'help> From<&'_ ArgGroup<'help>> for ArgGroup<'help> {
}
}
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
impl<'help> From<&'help Yaml> for ArgGroup<'help> {
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
fn from(y: &'help Yaml) -> Self {
let b = y.as_hash().expect("ArgGroup::from::<Yaml> expects a table");
// We WANT this to panic on error...so expect() is good.

View file

@ -86,7 +86,7 @@ impl SubCommand {
App::new(name)
}
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[deprecated(
since = "3.0.0",

View file

@ -1,4 +1,4 @@
/// Deprecated in [Issue #9](https://github.com/epage/clapng/issues/9), maybe [`clap::Parser`][crate::Parser] would fit your use case?
/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
#[cfg(feature = "yaml")]
#[deprecated(
since = "3.0.0",