From b1718022659822bc6ef277c5aad26dcc3fc4a619 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:16:22 -0600 Subject: [PATCH 1/6] docs: Ensure IntoApp is visible --- src/lib.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index dd244e44bcd..9d31ae37caf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -57,7 +57,6 @@ pub use clap_derive::{self, *}; /// Deprecated, replaced with [`CommandFactory`] #[deprecated(since = "3.0.0", note = "Replaced with `CommandFactory`")] -#[doc(hidden)] pub use CommandFactory as IntoApp; /// Deprecated, replaced with [`Parser`] #[deprecated(since = "3.0.0", note = "Replaced with `Parser`")] From 15c7abb1965c1f3841c79f425e53fbc37b1bbf5f Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:23:40 -0600 Subject: [PATCH 2/6] docs(parser): Fix ArgMatches::value_source documentation --- src/parse/matches/arg_matches.rs | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/parse/matches/arg_matches.rs b/src/parse/matches/arg_matches.rs index 3815f8e1aba..ab854f60bb4 100644 --- a/src/parse/matches/arg_matches.rs +++ b/src/parse/matches/arg_matches.rs @@ -626,10 +626,7 @@ impl ArgMatches { self.args.contains_key(&id) } - /// Check if an argument was present at runtime. - /// - /// *NOTE:* This will always return `true` if [`default_value`] has been set. - /// [`occurrences_of`] can be used to check if a value is present at runtime. + /// Report where argument value came from /// /// # Panics /// @@ -638,7 +635,7 @@ impl ArgMatches { /// # Examples /// /// ```rust - /// # use clap::{Command, Arg}; + /// # use clap::{Command, Arg, ValueSource}; /// let m = Command::new("myprog") /// .arg(Arg::new("debug") /// .short('d')) @@ -646,7 +643,7 @@ impl ArgMatches { /// "myprog", "-d" /// ]); /// - /// assert!(m.is_present("debug")); + /// assert_eq!(m.value_source("debug"), Some(ValueSource::CommandLine)); /// ``` /// /// [`default_value`]: crate::Arg::default_value() From e2136f9a6ae7fe8284a655dd0ab9bdee648da87b Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:26:48 -0600 Subject: [PATCH 3/6] docs(contrib): Align release windows The README says 6-9 and we want to be clear that it isn't guarenteed there will be a release then. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa3e104cefd..592024a252b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,11 +35,11 @@ There are a few goals of `clap` that I'd like to maintain throughout contributio Our releases fall into one of: - Major releases which are reserved for breaking changes - - Released approximately every 6 months + - Aspire to at least 6-9 months between releases - Remove all deprecated functionality - Try to minimize new breaking changes to ease user transition and reduce time "we go dark" (unreleased feature-branch) - Minor releases which are for minor compatibility changes - - Released approximately every 2 months + - Aspire to at least 2 months between releases - Changes to MSRV - Deprecating existing functionality - `#[doc(hidden)]` all deprecated items in the prior minor release From 92d100279fefb0906ae5eb7a35148707b20cbc04 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:28:59 -0600 Subject: [PATCH 4/6] docs(changelog): Add missing deprecation --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e648f2e575e..9a49f603655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ Changes in behavior of note that are not guaranteed to be compatible across rele - *(error)* Deprecate `clap::AppSettings::WaitOnError`, leaving it to the user to implement - *(validation)* `clap::Command::subcommand_required(true).arg_required_else_help(true)` is now preferred over `clap::AppSettings::SubcommandRequiredElseHelp` (#3280) - *(builder)* `clap::AppSettings` are nearly all deprecated and replaced with builder methods and getters (#2717) +- *(builder)* `clap::ArgSettings` is deprecated and replaced with builder methods and getters (#2717) - *(builder)* `clap::Arg::id` and `clap::ArgGroup::id` are now preferred over `clap::Arg::name` and `clap::ArgGroup::name` (#3335) - *(help)* `clap::Command::next_help_heading` is now preferred over `clap::Command::help_heading` (#1807, #1553) - *(error)* `clap::error::ErrorKind` is now preferred over `clap::ErrorKind` (#3395) From 94e2727bd0df25b112e5533b57d9b7017119b46a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:30:26 -0600 Subject: [PATCH 5/6] docs(builder): Clarify command-wide --- src/build/command.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/build/command.rs b/src/build/command.rs index 603479d4a35..1c98c2321f6 100644 --- a/src/build/command.rs +++ b/src/build/command.rs @@ -837,7 +837,7 @@ impl<'help> App<'help> { } } -/// Command-wide Settings +/// Application-wide (i.e. global) Settings /// /// These settings will apply to the top-level command and all subcommands, by default. Some /// settings can be overridden in subcommands. From 3dd3993682b0fc0a08135c75eb727ddbd508a3d0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 15 Feb 2022 11:40:58 -0600 Subject: [PATCH 6/6] docs(builder): Add ToC to Command, Arg --- src/build/arg.rs | 19 +++++++++++++------ src/build/command.rs | 16 +++++++++++----- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/src/build/arg.rs b/src/build/arg.rs index 34aaaeaf21f..6d2c3787563 100644 --- a/src/build/arg.rs +++ b/src/build/arg.rs @@ -35,6 +35,12 @@ use crate::build::RegexRef; /// manually, or using a usage string which is far less verbose but has fewer options. You can also /// use a combination of the two methods to achieve the best of both worlds. /// +/// - [Basic API][crate::Arg#basic-api] +/// - [Value Handling][crate::Arg#value-handling] +/// - [Help][crate::Arg#help-1] +/// - [Advanced Argument Relations][crate::Arg#advanced-argument-relations] +/// - [Reflection][crate::Arg#reflection] +/// /// # Examples /// /// ```rust @@ -91,6 +97,7 @@ pub struct Arg<'help> { pub(crate) value_hint: ValueHint, } +/// # Basic API impl<'help> Arg<'help> { /// Create a new [`Arg`] with a unique name. /// @@ -946,7 +953,7 @@ impl<'help> Arg<'help> { } } -/// Value handling +/// # Value Handling impl<'help> Arg<'help> { /// Specifies that the argument takes a value at run time. /// @@ -2727,7 +2734,7 @@ impl<'help> Arg<'help> { } } -/// Help +/// # Help impl<'help> Arg<'help> { /// Sets the description of the argument for short help (`-h`). /// @@ -3284,7 +3291,7 @@ impl<'help> Arg<'help> { } } -/// Advanced argument relations +/// # Advanced Argument Relations impl<'help> Arg<'help> { /// The name of the [`ArgGroup`] the argument belongs to. /// @@ -4489,7 +4496,7 @@ impl<'help> Arg<'help> { } } -/// Reflection +/// # Reflection impl<'help> Arg<'help> { /// Get the name of the argument #[inline] @@ -4800,7 +4807,7 @@ impl<'help> Arg<'help> { } } -/// Deprecated +/// # Deprecated impl<'help> Arg<'help> { /// Deprecated, replaced with [`Arg::new`] #[deprecated(since = "3.0.0", note = "Replaced with `Arg::new`")] @@ -5017,7 +5024,7 @@ impl<'help> Arg<'help> { } } -// Internally used only +/// # Internally used only impl<'help> Arg<'help> { pub(crate) fn _build(&mut self) { if self.is_positional() { diff --git a/src/build/command.rs b/src/build/command.rs index 1c98c2321f6..85bc30294e9 100644 --- a/src/build/command.rs +++ b/src/build/command.rs @@ -43,6 +43,12 @@ use crate::build::debug_asserts::assert_app; /// [`CommandFactory::into_app`][crate::CommandFactory::into_app] to access the /// `Command`. /// +/// - [Basic API][crate::App#basic-api] +/// - [Application-wide Settings][crate::App#application-wide-settings] +/// - [Command-specific Settings][crate::App#command-specific-settings] +/// - [Subcommand-specific Settings][crate::App#subcommand-specific-settings] +/// - [Reflection][crate::App#reflection] +/// /// # Examples /// /// ```no_run @@ -103,7 +109,7 @@ pub struct App<'help> { subcommand_heading: Option<&'help str>, } -/// Basic API +/// # Basic API impl<'help> App<'help> { /// Creates a new instance of an `Command`. /// @@ -837,7 +843,7 @@ impl<'help> App<'help> { } } -/// Application-wide (i.e. global) Settings +/// # Application-wide Settings /// /// These settings will apply to the top-level command and all subcommands, by default. Some /// settings can be overridden in subcommands. @@ -1323,7 +1329,7 @@ impl<'help> App<'help> { } } -/// Command-specific Settings +/// # Command-specific Settings /// /// These apply only to the current command and are not inherited by subcommands. impl<'help> App<'help> { @@ -2173,7 +2179,7 @@ impl<'help> App<'help> { } } -/// Subcommand-specific Settings +/// # Subcommand-specific Settings impl<'help> App<'help> { /// Sets the short version of the subcommand flag without the preceding `-`. /// @@ -3154,7 +3160,7 @@ impl<'help> App<'help> { } } -/// Reflection +/// # Reflection impl<'help> App<'help> { #[inline] pub(crate) fn get_usage_name(&self) -> Option<&str> {