From 6c7126b156ac220956247e9434ae67a9a4dba869 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Fri, 11 Feb 2022 18:42:26 -0600
Subject: [PATCH] docs: Hide items deprecated in 3.0.0

We left them in the docs for a period of time to help people find docs
for code that was still in use.  Balancing that with the need for clean
docs, it seems like 3.1 is an appropriate time to mark them hidden in
the docs.
---
 src/build/app.rs          | 19 +++++++++++++++++++
 src/build/app_settings.rs | 12 ++++++++++++
 src/build/arg.rs          | 16 ++++++++++++++++
 src/build/arg_group.rs    |  2 ++
 src/build/arg_settings.rs |  3 +++
 src/derive.rs             |  6 ++++++
 src/error/mod.rs          |  1 +
 src/lib.rs                |  5 +++++
 src/macros.rs             |  7 +++++++
 9 files changed, 71 insertions(+)

diff --git a/src/build/app.rs b/src/build/app.rs
index 6ab599671f0..afb9d98cf4a 100644
--- a/src/build/app.rs
+++ b/src/build/app.rs
@@ -3615,6 +3615,7 @@ impl<'help> App<'help> {
         since = "3.0.0",
         note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
     )]
+    #[doc(hidden)]
     pub fn from_yaml(y: &'help Yaml) -> Self {
         #![allow(deprecated)]
         let yaml_file_hash = y.as_hash().expect("YAML file must be a hash");
@@ -3702,6 +3703,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::override_usage`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::override_usage`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn usage<S: Into<&'help str>>(self, usage: S) -> Self {
         self.override_usage(usage)
@@ -3709,6 +3711,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::override_help`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::override_help`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn help<S: Into<&'help str>>(self, help: S) -> Self {
         self.override_help(help)
@@ -3716,6 +3719,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::mut_arg`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn help_short(self, c: char) -> Self {
         self.mut_arg("help", |a| a.short(c))
@@ -3723,6 +3727,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::mut_arg`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn version_short(self, c: char) -> Self {
         self.mut_arg("version", |a| a.short(c))
@@ -3730,6 +3735,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::mut_arg`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn help_message(self, s: impl Into<&'help str>) -> Self {
         self.mut_arg("help", |a| a.help(s.into()))
@@ -3737,6 +3743,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::mut_arg`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn version_message(self, s: impl Into<&'help str>) -> Self {
         self.mut_arg("version", |a| a.help(s.into()))
@@ -3744,6 +3751,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::help_template`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::help_template`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn template<S: Into<&'help str>>(self, s: S) -> Self {
         self.help_template(s)
@@ -3751,6 +3759,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::setting(a| b)`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::setting(a | b)`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn settings(mut self, settings: &[AppSettings]) -> Self {
         for s in settings {
@@ -3761,6 +3770,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::unset_setting(a| b)`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::unset_setting(a | b)`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn unset_settings(mut self, settings: &[AppSettings]) -> Self {
         for s in settings {
@@ -3771,6 +3781,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::global_setting(a| b)`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::global_setting(a | b)`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn global_settings(mut self, settings: &[AppSettings]) -> Self {
         for s in settings {
@@ -3782,6 +3793,7 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::term_width`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::term_width`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn set_term_width(self, width: usize) -> Self {
         self.term_width(width)
@@ -3789,6 +3801,7 @@ impl<'help> App<'help> {
 
     /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
     #[deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")]
+    #[doc(hidden)]
     #[must_use]
     pub fn arg_from_usage(self, usage: &'help str) -> Self {
         #![allow(deprecated)]
@@ -3797,6 +3810,7 @@ impl<'help> App<'help> {
 
     /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
     #[deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")]
+    #[doc(hidden)]
     #[must_use]
     pub fn args_from_usage(mut self, usage: &'help str) -> Self {
         #![allow(deprecated)]
@@ -3812,24 +3826,28 @@ impl<'help> App<'help> {
 
     /// Deprecated, replaced with [`App::render_version`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::render_version`")]
+    #[doc(hidden)]
     pub fn write_version<W: Write>(&self, w: &mut W) -> ClapResult<()> {
         write!(w, "{}", self.render_version()).map_err(From::from)
     }
 
     /// Deprecated, replaced with [`App::render_long_version`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::render_long_version`")]
+    #[doc(hidden)]
     pub fn write_long_version<W: Write>(&self, w: &mut W) -> ClapResult<()> {
         write!(w, "{}", self.render_long_version()).map_err(From::from)
     }
 
     /// Deprecated, replaced with [`App::try_get_matches`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches`")]
+    #[doc(hidden)]
     pub fn get_matches_safe(self) -> ClapResult<ArgMatches> {
         self.try_get_matches()
     }
 
     /// Deprecated, replaced with [`App::try_get_matches_from`]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches_from`")]
+    #[doc(hidden)]
     pub fn get_matches_from_safe<I, T>(self, itr: I) -> ClapResult<ArgMatches>
     where
         I: IntoIterator<Item = T>,
@@ -3843,6 +3861,7 @@ impl<'help> App<'help> {
         since = "3.0.0",
         note = "Replaced with `App::try_get_matches_from_mut`"
     )]
+    #[doc(hidden)]
     pub fn get_matches_from_safe_borrow<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches>
     where
         I: IntoIterator<Item = T>,
diff --git a/src/build/app_settings.rs b/src/build/app_settings.rs
index d8e8e0b30c0..7998bc93ac6 100644
--- a/src/build/app_settings.rs
+++ b/src/build/app_settings.rs
@@ -342,6 +342,7 @@ pub enum AppSettings {
         since = "3.0.0",
         note = "Replaced with `AppSettings::AllowHyphenValues`"
     )]
+    #[doc(hidden)]
     AllowLeadingHyphen,
 
     /// Deprecated, this is now the default, see [`AppSettings::AllowInvalidUtf8ForExternalSubcommands`] and [`ArgSettings::AllowInvalidUtf8`][crate::ArgSettings::AllowInvalidUtf8] for the opposite.
@@ -349,30 +350,37 @@ pub enum AppSettings {
         since = "3.0.0",
         note = "This is now the default see `AppSettings::AllowInvalidUtf8ForExternalSubcommands` and `ArgSettings::AllowInvalidUtf8` for the opposite."
     )]
+    #[doc(hidden)]
     StrictUtf8,
 
     /// Deprecated, this is now the default
     #[deprecated(since = "3.0.0", note = "This is now the default")]
+    #[doc(hidden)]
     UnifiedHelpMessage,
 
     /// Deprecated, this is now the default
     #[deprecated(since = "3.0.0", note = "This is now the default")]
+    #[doc(hidden)]
     ColoredHelp,
 
     /// Deprecated, see [`App::color`][crate::App::color]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::color`")]
+    #[doc(hidden)]
     ColorAuto,
 
     /// Deprecated, replaced with [`App::color`][crate::App::color]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::color`")]
+    #[doc(hidden)]
     ColorAlways,
 
     /// Deprecated, replaced with [`App::color`][crate::App::color]
     #[deprecated(since = "3.0.0", note = "Replaced with `App::color`")]
+    #[doc(hidden)]
     ColorNever,
 
     /// Deprecated, replaced with [`AppSettings::DisableHelpFlag`]
     #[deprecated(since = "3.0.0", note = "Replaced with `AppSettings::DisableHelpFlag`")]
+    #[doc(hidden)]
     DisableHelpFlags,
 
     /// Deprecated, replaced with [`AppSettings::DisableVersionFlag`]
@@ -380,6 +388,7 @@ pub enum AppSettings {
         since = "3.0.0",
         note = "Replaced with `AppSettings::DisableVersionFlag`"
     )]
+    #[doc(hidden)]
     DisableVersion,
 
     /// Deprecated, replaced with [`AppSettings::PropagateVersion`]
@@ -387,6 +396,7 @@ pub enum AppSettings {
         since = "3.0.0",
         note = "Replaced with `AppSettings::PropagateVersion`"
     )]
+    #[doc(hidden)]
     GlobalVersion,
 
     /// Deprecated, replaced with [`AppSettings::HidePossibleValues`]
@@ -394,10 +404,12 @@ pub enum AppSettings {
         since = "3.0.0",
         note = "Replaced with AppSettings::HidePossibleValues"
     )]
+    #[doc(hidden)]
     HidePossibleValuesInHelp,
 
     /// Deprecated, this is now the default
     #[deprecated(since = "3.0.0", note = "This is now the default")]
+    #[doc(hidden)]
     UnifiedHelp,
 
     /// If the app is already built, used for caching.
diff --git a/src/build/arg.rs b/src/build/arg.rs
index 6d3bd67ab22..f923404a38e 100644
--- a/src/build/arg.rs
+++ b/src/build/arg.rs
@@ -4804,6 +4804,7 @@ impl<'help> Arg<'help> {
 impl<'help> Arg<'help> {
     /// Deprecated, replaced with [`Arg::new`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::new`")]
+    #[doc(hidden)]
     pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
         Self::new(n)
     }
@@ -4814,6 +4815,7 @@ impl<'help> Arg<'help> {
         since = "3.0.0",
         note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
     )]
+    #[doc(hidden)]
     pub fn from_yaml(y: &'help Yaml) -> Self {
         #![allow(deprecated)]
         let yaml_file_hash = y.as_hash().expect("YAML file must be a hash");
@@ -4883,12 +4885,14 @@ impl<'help> Arg<'help> {
 
     /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
     #[deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")]
+    #[doc(hidden)]
     pub fn from_usage(u: &'help str) -> Self {
         UsageParser::from_usage(u).parse()
     }
 
     /// Deprecated, replaced with [`Arg::required_unless_present`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_unless_present`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn required_unless<T: Key>(self, arg_id: T) -> Self {
         self.required_unless_present(arg_id)
@@ -4899,6 +4903,7 @@ impl<'help> Arg<'help> {
         since = "3.0.0",
         note = "Replaced with `Arg::required_unless_present_all`"
     )]
+    #[doc(hidden)]
     #[must_use]
     pub fn required_unless_all<T, I>(self, names: I) -> Self
     where
@@ -4913,6 +4918,7 @@ impl<'help> Arg<'help> {
         since = "3.0.0",
         note = "Replaced with `Arg::required_unless_present_any`"
     )]
+    #[doc(hidden)]
     #[must_use]
     pub fn required_unless_one<T, I>(self, names: I) -> Self
     where
@@ -4924,6 +4930,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::required_if_eq`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn required_if<T: Key>(self, arg_id: T, val: &'help str) -> Self {
         self.required_if_eq(arg_id, val)
@@ -4931,6 +4938,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::required_if_eq_any`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq_any`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn required_ifs<T: Key>(self, ifs: &[(T, &'help str)]) -> Self {
         self.required_if_eq_any(ifs)
@@ -4938,6 +4946,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::hide`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::hide`")]
+    #[doc(hidden)]
     #[inline]
     #[must_use]
     pub fn hidden(self, yes: bool) -> Self {
@@ -4946,6 +4955,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::ignore_case`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::ignore_case`")]
+    #[doc(hidden)]
     #[inline]
     #[must_use]
     pub fn case_insensitive(self, yes: bool) -> Self {
@@ -4954,6 +4964,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::forbid_empty_values`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::forbid_empty_values`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn empty_values(self, yes: bool) -> Self {
         self.forbid_empty_values(!yes)
@@ -4965,6 +4976,7 @@ impl<'help> Arg<'help> {
         since = "3.0.0",
         note = "Split into `Arg::multiple_occurrences` (most likely what you want)  and `Arg::multiple_values`"
     )]
+    #[doc(hidden)]
     #[must_use]
     pub fn multiple(self, yes: bool) -> Self {
         self.multiple_occurrences(yes).multiple_values(yes)
@@ -4972,6 +4984,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::hide_short_help`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::hide_short_help`")]
+    #[doc(hidden)]
     #[inline]
     #[must_use]
     pub fn hidden_short_help(self, yes: bool) -> Self {
@@ -4980,6 +4993,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::hide_long_help`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::hide_long_help`")]
+    #[doc(hidden)]
     #[inline]
     #[must_use]
     pub fn hidden_long_help(self, yes: bool) -> Self {
@@ -4988,6 +5002,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::setting`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::setting`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn set(self, s: ArgSettings) -> Self {
         self.setting(s)
@@ -4995,6 +5010,7 @@ impl<'help> Arg<'help> {
 
     /// Deprecated, replaced with [`Arg::unset_setting`]
     #[deprecated(since = "3.0.0", note = "Replaced with `Arg::unset_setting`")]
+    #[doc(hidden)]
     #[must_use]
     pub fn unset(self, s: ArgSettings) -> Self {
         self.unset_setting(s)
diff --git a/src/build/arg_group.rs b/src/build/arg_group.rs
index 20588578b49..b635a23725f 100644
--- a/src/build/arg_group.rs
+++ b/src/build/arg_group.rs
@@ -434,6 +434,7 @@ impl<'help> ArgGroup<'help> {
 
     /// Deprecated, replaced with [`ArgGroup::new`]
     #[deprecated(since = "3.0.0", note = "Replaced with `ArgGroup::new`")]
+    #[doc(hidden)]
     pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
         Self::new(n)
     }
@@ -444,6 +445,7 @@ impl<'help> ArgGroup<'help> {
         since = "3.0.0",
         note = "Maybe clap::Parser would fit your use case? (Issue #3087)"
     )]
+    #[doc(hidden)]
     pub fn from_yaml(yaml: &'help Yaml) -> Self {
         Self::from(yaml)
     }
diff --git a/src/build/arg_settings.rs b/src/build/arg_settings.rs
index 935d102ccfb..dee79565b9c 100644
--- a/src/build/arg_settings.rs
+++ b/src/build/arg_settings.rs
@@ -57,6 +57,7 @@ pub enum ArgSettings {
         since = "3.0.0",
         note = "Split into `ArgSettings::MultipleOccurrences` (most likely what you want)  and `ArgSettings::MultipleValues`"
     )]
+    #[doc(hidden)]
     Multiple,
     /// Deprecated, replaced with [`Arg::forbid_empty_values`] and
     /// [`Arg::is_forbid_empty_values_set`]
@@ -122,6 +123,7 @@ pub enum ArgSettings {
         since = "3.0.0",
         note = "Replaced with `ArgSettings::AllowHyphenValues`"
     )]
+    #[doc(hidden)]
     AllowLeadingHyphen,
     /// Deprecated, replaced with [`Arg::require_equals`] and [`Arg::is_require_equals_set`]
     #[deprecated(
@@ -149,6 +151,7 @@ pub enum ArgSettings {
     IgnoreCase,
     /// Deprecated, replaced with [`ArgSettings::IgnoreCase`]
     #[deprecated(since = "3.0.0", note = "Replaced with `ArgSettings::IgnoreCase`")]
+    #[doc(hidden)]
     CaseInsensitive,
     /// Deprecated, replaced with [`Arg::hide_env`] and [`Arg::is_hide_env_set`]
     #[deprecated(
diff --git a/src/derive.rs b/src/derive.rs
index 8b9f86fdba5..ffe70896a54 100644
--- a/src/derive.rs
+++ b/src/derive.rs
@@ -160,6 +160,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::clap` is replaced with `IntoApp::into_app` (derived as part of `Parser`)"
     )]
+    #[doc(hidden)]
     fn clap<'help>() -> App<'help> {
         <Self as IntoApp>::into_app()
     }
@@ -170,6 +171,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::from_clap` is replaced with `FromArgMatches::from_arg_matches` (derived as part of `Parser`)"
     )]
+    #[doc(hidden)]
     fn from_clap(matches: &ArgMatches) -> Self {
         <Self as FromArgMatches>::from_arg_matches(matches).unwrap()
     }
@@ -179,6 +181,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::from_args` is replaced with `Parser::parse` (note the change in derives)"
     )]
+    #[doc(hidden)]
     fn from_args() -> Self {
         Self::parse()
     }
@@ -188,6 +191,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::from_args_safe` is replaced with `Parser::try_parse` (note the change in derives)"
     )]
+    #[doc(hidden)]
     fn from_args_safe() -> Result<Self, Error> {
         Self::try_parse()
     }
@@ -197,6 +201,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::from_iter` is replaced with `Parser::parse_from` (note the change in derives)"
     )]
+    #[doc(hidden)]
     fn from_iter<I, T>(itr: I) -> Self
     where
         I: IntoIterator<Item = T>,
@@ -211,6 +216,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         since = "3.0.0",
         note = "`StructOpt::from_iter_safe` is replaced with `Parser::try_parse_from` (note the change in derives)"
     )]
+    #[doc(hidden)]
     fn from_iter_safe<I, T>(itr: I) -> Result<Self, Error>
     where
         I: IntoIterator<Item = T>,
diff --git a/src/error/mod.rs b/src/error/mod.rs
index 25ccd2a3fb6..ee07a2a86d8 100644
--- a/src/error/mod.rs
+++ b/src/error/mod.rs
@@ -151,6 +151,7 @@ impl Error {
     ///
     /// [`App::error`]: crate::App::error
     #[deprecated(since = "3.0.0", note = "Replaced with `App::error`")]
+    #[doc(hidden)]
     pub fn with_description(description: String, kind: ErrorKind) -> Self {
         Error::raw(kind, description)
     }
diff --git a/src/lib.rs b/src/lib.rs
index 9a48ae8629b..369ee0d7d58 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -44,6 +44,7 @@ pub use crate::error::{ErrorKind, Result};
     since = "3.0.0",
     note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
 )]
+#[doc(hidden)]
 pub use yaml_rust::YamlLoader;
 
 #[cfg(feature = "derive")]
@@ -52,6 +53,7 @@ pub use clap_derive::{self, *};
 
 /// Deprecated, replaced with [`Parser`]
 #[deprecated(since = "3.0.0", note = "Replaced with `Parser`")]
+#[doc(hidden)]
 pub use Parser as StructOpt;
 
 #[cfg(any(feature = "derive", feature = "cargo"))]
@@ -84,6 +86,7 @@ const INVALID_UTF8: &str = "unexpected invalid UTF-8 code point";
     since = "3.0.0",
     note = "Replaced with `App::new` unless you intended the `Subcommand` trait"
 )]
+#[doc(hidden)]
 #[derive(Debug, Copy, Clone)]
 pub struct SubCommand {}
 
@@ -92,6 +95,7 @@ impl SubCommand {
     /// Deprecated, replaced with [`App::new`].
     /// Did you mean Subcommand (lower-case c)?
     #[deprecated(since = "3.0.0", note = "Replaced with `App::new`")]
+    #[doc(hidden)]
     pub fn with_name<'help>(name: &str) -> App<'help> {
         App::new(name)
     }
@@ -102,6 +106,7 @@ impl SubCommand {
         since = "3.0.0",
         note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
     )]
+    #[doc(hidden)]
     pub fn from_yaml(yaml: &yaml_rust::Yaml) -> App {
         #![allow(deprecated)]
         App::from_yaml(yaml)
diff --git a/src/macros.rs b/src/macros.rs
index 701a8ef152f..e6a3bc11f17 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -4,6 +4,7 @@
     since = "3.0.0",
     note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
 )]
+#[doc(hidden)]
 #[macro_export]
 macro_rules! load_yaml {
     ($yaml:expr) => {
@@ -15,6 +16,7 @@ macro_rules! load_yaml {
 /// Deprecated, replaced with [`ArgMatches::value_of_t`][crate::ArgMatches::value_of_t]
 #[macro_export]
 #[deprecated(since = "3.0.0", note = "Replaced with `ArgMatches::value_of_t`")]
+#[doc(hidden)]
 macro_rules! value_t {
     ($m:ident, $v:expr, $t:ty) => {
         $crate::value_t!($m.value_of($v), $t)
@@ -30,6 +32,7 @@ macro_rules! value_t {
     since = "3.0.0",
     note = "Replaced with `ArgMatches::value_of_t_or_exit`"
 )]
+#[doc(hidden)]
 macro_rules! value_t_or_exit {
     ($m:ident, $v:expr, $t:ty) => {
         value_t_or_exit!($m.value_of($v), $t)
@@ -42,6 +45,7 @@ macro_rules! value_t_or_exit {
 /// Deprecated, replaced with [`ArgMatches::values_of_t`][crate::ArgMatches::value_of_t]
 #[macro_export]
 #[deprecated(since = "3.0.0", note = "Replaced with `ArgMatches::values_of_t`")]
+#[doc(hidden)]
 macro_rules! values_t {
     ($m:ident, $v:expr, $t:ty) => {
         values_t!($m.values_of($v), $t)
@@ -57,6 +61,7 @@ macro_rules! values_t {
     since = "3.0.0",
     note = "Replaced with `ArgMatches::values_of_t_or_exit`"
 )]
+#[doc(hidden)]
 macro_rules! values_t_or_exit {
     ($m:ident, $v:expr, $t:ty) => {
         values_t_or_exit!($m.values_of($v), $t)
@@ -68,6 +73,7 @@ macro_rules! values_t_or_exit {
 
 /// Deprecated, replaced with [`ArgEnum`][crate::ArgEnum]
 #[deprecated(since = "3.0.0", note = "Replaced with `ArgEnum`")]
+#[doc(hidden)]
 #[macro_export]
 macro_rules! arg_enum {
     (@as_item $($i:item)*) => ($($i)*);
@@ -632,6 +638,7 @@ macro_rules! arg {
     since = "3.0.0",
     note = "Replaced with `clap::Parser` for a declarative API (Issue clap-rs/clap#2835)"
 )]
+#[doc(hidden)]
 #[macro_export]
 macro_rules! clap_app {
     (@app ($builder:expr)) => { $builder };