docs: Clarify deprecations

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**

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)]

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()

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::<Yaml> expects a table");
         // We WANT this to panic on error...so expect() is good.

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",

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",