From 122c227ebc9878fe8b9ecb3ddbb448ac30c2bd73 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Sat, 9 Oct 2021 14:06:37 -0500 Subject: [PATCH] docs: Annotate with required features --- .github/workflows/ci.yml | 4 ++-- Cargo.toml | 3 ++- src/build/app/mod.rs | 4 ++-- src/build/arg/mod.rs | 7 +++++++ src/build/arg/regex.rs | 1 + src/build/arg/settings.rs | 2 ++ src/build/arg_group.rs | 1 + src/lib.rs | 1 + src/macros.rs | 7 +++++++ src/parse/matches/matched_arg.rs | 1 + 10 files changed, 26 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c6625bc772c..f1ad6415c66 100644 --- a/.github/workflows/ci.yml +++ b/.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' diff --git a/Cargo.toml b/Cargo.toml index 2b60560bacc..d31ffe8b220 100644 --- a/Cargo.toml +++ b/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] diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index 29e0671ace1..7a8f1f9fe10 100644 --- a/src/build/app/mod.rs +++ b/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 { diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index 84ae2583cc9..5979ceb320b 100644 --- a/src/build/arg/mod.rs +++ b/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>, @@ -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. /// diff --git a/src/build/arg/regex.rs b/src/build/arg/regex.rs index d569e007fa0..bd1e3ad419b 100644 --- a/src/build/arg/regex.rs +++ b/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> { diff --git a/src/build/arg/settings.rs b/src/build/arg/settings.rs index 152ad456888..d8f021e6ea6 100644 --- a/src/build/arg/settings.rs +++ b/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, diff --git a/src/build/arg_group.rs b/src/build/arg_group.rs index 33b5929eda7..9403ae08292 100644 --- a/src/build/arg_group.rs +++ b/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. /// diff --git a/src/lib.rs b/src/lib.rs index 7258c03ec70..75823a7c13d 100644 --- a/src/lib.rs +++ b/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`"); diff --git a/src/macros.rs b/src/macros.rs index 723027e456b..79949ba9b68 100644 --- a/src/macros.rs +++ b/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 { () => { diff --git a/src/parse/matches/matched_arg.rs b/src/parse/matches/matched_arg.rs index 361d430a67c..ed5716aa6b7 100644 --- a/src/parse/matches/matched_arg.rs +++ b/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,