docs: Annotate with required features

.github/workflows/ci.yml

@@ -139,13 +139,13 @@ jobs:
         if: matrix.features == 'all'
         with:
           command: test
-          args: --features "wrap_help yaml regex unstable-replace"
+          args: --features "wrap_help yaml regex unstable-replace nightly"
       - name: Check debug
         uses: actions-rs/cargo@v1
         if: matrix.features == 'all'
         with:
           command: check
-          args: --features "wrap_help yaml regex unstable-replace debug"
+          args: --features "wrap_help yaml regex unstable-replace nightly debug"
       - name: Test release
         uses: actions-rs/cargo@v1
         if: matrix.features == 'release'

Cargo.toml

@@ -105,6 +105,7 @@ unicode = ["textwrap/unicode-width", "unicase"]  # Support for unicode character
 # Optional
 wrap_help = ["terminal_size", "textwrap/terminal_size"]
 yaml = ["yaml-rust"]
+nightly = []
 
 # In-work features
 unstable-replace = []
@@ -117,7 +118,7 @@ lto = true
 codegen-units = 1
 
 [package.metadata.docs.rs]
-features = ["yaml", "regex", "unstable-replace"]
+features = ["yaml", "regex", "unstable-replace", "nightly"]
 targets = ["x86_64-unknown-linux-gnu"]
 
 [workspace]

src/build/app/mod.rs

@@ -1437,8 +1437,6 @@ impl<'help> App<'help> {
 
     /// Replaces an argument or subcommand used on the CLI at runtime with other arguments or subcommands.
     ///
-    /// **Note:** This is gated behind [`unstable-replace`](https://github.com/clap-rs/clap/issues/2836)
-    ///
     /// When this method is used, `name` is removed from the CLI, and `target`
     /// is inserted in its place. Parsing continues as if the user typed
     /// `target` instead of `name`.
@@ -1542,6 +1540,7 @@ impl<'help> App<'help> {
     /// [`App::replace`]: App::replace()
     #[inline]
     #[cfg(feature = "unstable-replace")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "unstable-replace")))]
     pub fn replace(mut self, name: &'help str, target: &'help [&'help str]) -> Self {
         self.replacers.insert(name, target);
         self
@@ -2837,6 +2836,7 @@ impl<'help> Index<&'_ Id> for App<'help> {
 }
 
 #[cfg(feature = "yaml")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "yaml")))]
 impl<'help> From<&'help Yaml> for App<'help> {
     #[allow(clippy::cognitive_complexity)]
     fn from(y: &'help Yaml) -> Self {

src/build/arg/mod.rs

@@ -266,6 +266,7 @@ impl<'help> Arg<'help> {
     /// assert_eq!(Some(OsStr::new("ENVIRONMENT")), arg.get_env());
     /// ```
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     pub fn get_env(&self) -> Option<&OsStr> {
         self.env.as_ref().map(|x| x.0)
     }
@@ -2295,6 +2296,7 @@ impl<'help> Arg<'help> {
     /// assert_eq!(res.err().unwrap().kind, ErrorKind::ValueValidation)
     /// ```
     #[cfg(feature = "regex")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "regex")))]
     pub fn validator_regex(
         self,
         regex: impl Into<RegexRef<'help>>,
@@ -3219,6 +3221,7 @@ impl<'help> Arg<'help> {
     /// [`Arg::takes_value(true)`]: Arg::takes_value()
     /// [`Arg::use_delimiter(true)`]: Arg::use_delimiter()
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     #[inline]
     pub fn env(self, name: &'help str) -> Self {
         self.env_os(OsStr::new(name))
@@ -3228,6 +3231,7 @@ impl<'help> Arg<'help> {
     /// from the environment if available in the exact same manner as [`Arg::env`] only using
     /// [`OsStr`]s instead.
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     #[inline]
     pub fn env_os(mut self, name: &'help OsStr) -> Self {
         self.env = Some((name, env::var_os(name)));
@@ -4019,6 +4023,7 @@ impl<'help> Arg<'help> {
     /// If we were to run the above program with `--help` the `[env: MODE]` portion of the help
     /// text would be omitted.
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     #[inline]
     pub fn hide_env(self, hide: bool) -> Self {
         if hide {
@@ -4057,6 +4062,7 @@ impl<'help> Arg<'help> {
     /// If we were to run the above program with `$ CONNECT=super_secret connect --help` the
     /// `[default: CONNECT=super_secret]` portion of the help text would be omitted.
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     #[inline]
     pub fn hide_env_values(self, hide: bool) -> Self {
         if hide {
@@ -4786,6 +4792,7 @@ impl<'help> Arg<'help> {
 }
 
 #[cfg(feature = "yaml")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "yaml")))]
 impl<'help> From<&'help Yaml> for Arg<'help> {
     /// Creates a new instance of [`Arg`] from a .yaml (YAML) file.
     ///

src/build/arg/regex.rs

@@ -10,6 +10,7 @@ use std::borrow::Cow;
 ///
 /// [`Cow`]: std::borrow::Cow
 #[derive(Debug, Clone)]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "regex")))]
 pub struct RegexRef<'a>(Cow<'a, Regex>);
 
 impl<'a> Deref for RegexRef<'a> {

src/build/arg/settings.rs

@@ -115,10 +115,12 @@ pub enum ArgSettings {
     IgnoreCase,
     /// Hides environment variable arguments from the help message
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     HideEnv,
     /// Hides any values currently assigned to ENV variables in the help message (good for sensitive
     /// information)
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     HideEnvValues,
     /// The argument should **not** be shown in short help text
     HiddenShortHelp,

src/build/arg_group.rs

@@ -424,6 +424,7 @@ impl<'help> From<&'_ ArgGroup<'help>> for ArgGroup<'help> {
 }
 
 #[cfg(feature = "yaml")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "yaml")))]
 impl<'help> From<&'help Yaml> for ArgGroup<'help> {
     /// Creates a new instance of `ArgGroup` from a .yaml (YAML) file.
     ///

src/lib.rs

@@ -19,6 +19,7 @@
 #![forbid(unsafe_code)]
 // TODO: https://github.com/rust-lang/rust-clippy/issues/7290
 #![allow(clippy::single_component_path_imports)]
+#![cfg_attr(feature = "nightly", feature(doc_cfg))]
 
 #[cfg(not(feature = "std"))]
 compile_error!("`std` feature is currently required to build `clap`");

src/macros.rs

@@ -24,6 +24,7 @@
 /// # }
 /// ```
 #[cfg(feature = "yaml")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "yaml")))]
 #[macro_export]
 macro_rules! load_yaml {
     ($yaml:expr) => {
@@ -49,6 +50,7 @@ macro_rules! load_yaml {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! crate_license {
     () => {{
@@ -79,6 +81,7 @@ macro_rules! crate_license {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! crate_version {
     () => {
@@ -108,6 +111,7 @@ macro_rules! crate_version {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! crate_authors {
     ($sep:expr) => {{
@@ -138,6 +142,7 @@ macro_rules! crate_authors {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! crate_description {
     () => {
@@ -159,6 +164,7 @@ macro_rules! crate_description {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! crate_name {
     () => {
@@ -190,6 +196,7 @@ macro_rules! crate_name {
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
+#[cfg_attr(feature = "nightly", doc(cfg(feature = "cargo")))]
 #[macro_export]
 macro_rules! app_from_crate {
     () => {

src/parse/matches/matched_arg.rs

@@ -12,6 +12,7 @@ use crate::INTERNAL_ERROR_MSG;
 pub(crate) enum ValueType {
     Unknown,
     #[cfg(feature = "env")]
+    #[cfg_attr(feature = "nightly", doc(cfg(feature = "env")))]
     EnvVariable,
     CommandLine,
     DefaultValue,