Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Annotate with required features #2842

Closed
wants to merge 1 commit into from
Closed

docs: Annotate with required features #2842

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
3 changes: 2 additions & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = []
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please rename this feature to doc which is more meaningful and which is what we used to do before to use some nightly doc features.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imo the name should make clear it requires the nightly toolchain. I also don't see a reason for us to restrict this flag to jsut docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about nightly-doc? We want to differentiate between the features for docs.rs and actual features (if we have any).


# In-work features
unstable-replace = []
Expand All @@ -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]
Expand Down
4 changes: 2 additions & 2 deletions src/build/app/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 {
Expand Down
7 changes: 7 additions & 0 deletions src/build/arg/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down Expand Up @@ -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>>,
Expand Down Expand Up @@ -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))
Expand All @@ -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)));
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.
///
Expand Down
1 change: 1 addition & 0 deletions src/build/arg/regex.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> {
Expand Down
2 changes: 2 additions & 0 deletions src/build/arg/settings.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions src/build/arg_group.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand Down
1 change: 1 addition & 0 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`");
Expand Down
7 changes: 7 additions & 0 deletions src/macros.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
/// # }
/// ```
#[cfg(feature = "yaml")]
#[cfg_attr(feature = "nightly", doc(cfg(feature = "yaml")))]
#[macro_export]
macro_rules! load_yaml {
($yaml:expr) => {
Expand All @@ -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 {
() => {{
Expand Down Expand Up @@ -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 {
() => {
Expand Down Expand Up @@ -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) => {{
Expand Down Expand Up @@ -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 {
() => {
Expand All @@ -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 {
() => {
Expand Down Expand Up @@ -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 {
() => {
Expand Down
1 change: 1 addition & 0 deletions src/parse/matches/matched_arg.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down