From e5997c10012ffd790724edc660cb2a646b4cd82c Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 8 Dec 2021 11:11:26 -0600 Subject: [PATCH] docs: Clarify deprecations --- CHANGELOG.md | 17 ++++++++++------- src/build/app/mod.rs | 6 +++--- src/build/arg/mod.rs | 4 ++-- src/build/arg_group.rs | 6 +++--- src/lib.rs | 2 +- src/macros.rs | 2 +- 6 files changed, 20 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c6df1e9a..636b2313 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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** diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index fbaa6c2f..e67f072e 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -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)] diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index bba1257e..5096c8c6 100644 --- a/src/build/arg/mod.rs +++ b/src/build/arg/mod.rs @@ -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() diff --git a/src/build/arg_group.rs b/src/build/arg_group.rs index f2b733cb..451bd9fd 100644 --- a/src/build/arg_group.rs +++ b/src/build/arg_group.rs @@ -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:: expects a table"); // We WANT this to panic on error...so expect() is good. diff --git a/src/lib.rs b/src/lib.rs index 7846613c..56497ba0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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", diff --git a/src/macros.rs b/src/macros.rs index 7d2d6e2f..6c7406dd 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -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",