mirror of
https://github.com/clap-rs/clap
synced 2024-12-13 06:12:40 +00:00
Merge pull request #3475 from epage/fixes
docs: Polish in prep for 3.1.0
This commit is contained in:
Ed Page
GitHub
commit
9bc0af892d
6 changed files with 30 additions and 20 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
|
|
@ -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> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Command-wide 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> {
|
||||
|
|
|
|||
|
|
@ -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`")]
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
Loading…
Reference in a new issue