From 6f78e2a3ff01366f2e401ef30cadeb7b36ff334c Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 8 Nov 2024 11:07:48 -0600 Subject: [PATCH] docs: Highlight notes/warnings in a block --- clap_builder/src/builder/action.rs | 12 + clap_builder/src/builder/app_settings.rs | 4 + clap_builder/src/builder/arg.rs | 267 +++++++++++++++- clap_builder/src/builder/arg_group.rs | 24 ++ clap_builder/src/builder/command.rs | 297 ++++++++++++++++-- clap_builder/src/builder/os_str.rs | 4 + clap_builder/src/builder/possible_value.rs | 8 + clap_builder/src/builder/str.rs | 4 + clap_builder/src/builder/value_parser.rs | 4 + clap_builder/src/derive.rs | 16 + clap_builder/src/error/format.rs | 4 + clap_builder/src/macros.rs | 16 + .../src/parser/matches/arg_matches.rs | 20 ++ clap_builder/src/util/color.rs | 4 + clap_complete/src/aot/generator/mod.rs | 8 + clap_complete/src/aot/generator/utils.rs | 4 + clap_complete/src/env/mod.rs | 8 + clap_lex/src/lib.rs | 12 + examples/pacman.md | 4 + src/_derive/mod.rs | 8 + 20 files changed, 686 insertions(+), 42 deletions(-) diff --git a/clap_builder/src/builder/action.rs b/clap_builder/src/builder/action.rs index 9cd17012..2e8221d8 100644 --- a/clap_builder/src/builder/action.rs +++ b/clap_builder/src/builder/action.rs @@ -32,10 +32,14 @@ use crate::util::AnyValueId; pub enum ArgAction { /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches] /// + ///
+ /// /// **NOTE:** If the argument has previously been seen, it will result in a /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// + ///
+ /// /// # Examples /// /// ```rust @@ -87,10 +91,14 @@ pub enum ArgAction { /// No value is allowed. To optionally accept a value, see /// [`Arg::default_missing_value`][super::Arg::default_missing_value] /// + ///
+ /// /// **NOTE:** If the argument has previously been seen, it will result in a /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// + ///
+ /// /// # Examples /// /// ```rust @@ -162,10 +170,14 @@ pub enum ArgAction { /// No value is allowed. To optionally accept a value, see /// [`Arg::default_missing_value`][super::Arg::default_missing_value] /// + ///
+ /// /// **NOTE:** If the argument has previously been seen, it will result in a /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. /// + ///
+ /// /// # Examples /// /// ```rust diff --git a/clap_builder/src/builder/app_settings.rs b/clap_builder/src/builder/app_settings.rs index f9a87dad..8d1f24f6 100644 --- a/clap_builder/src/builder/app_settings.rs +++ b/clap_builder/src/builder/app_settings.rs @@ -35,9 +35,13 @@ impl std::ops::BitOr for AppFlags { /// Application level settings, which affect how [`Command`] operates /// +///
+/// /// **NOTE:** When these settings are used, they apply only to current command, and are *not* /// propagated down or up through child or parent subcommands /// +///
+/// /// [`Command`]: crate::Command #[derive(Debug, PartialEq, Copy, Clone)] #[repr(u8)] diff --git a/clap_builder/src/builder/arg.rs b/clap_builder/src/builder/arg.rs index 61949510..e3d0d7d0 100644 --- a/clap_builder/src/builder/arg.rs +++ b/clap_builder/src/builder/arg.rs @@ -98,10 +98,14 @@ impl Arg { /// The name is used to check whether or not the argument was used at /// runtime, get values, set relationships with other args, etc.. /// + ///
+ /// /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`]) /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also /// be displayed when the user prints the usage/help information of the program. /// + ///
+ /// /// # Examples /// /// ```rust @@ -188,8 +192,12 @@ impl Arg { /// own arguments, in which case `clap` simply will not assign those to the auto-generated /// `version` or `help` arguments. /// + ///
+ /// /// **NOTE:** Any leading `-` characters will be stripped /// + ///
+ /// /// # Examples /// /// To set `long` use a word containing valid UTF-8. If you supply a double leading @@ -456,19 +464,35 @@ impl Arg { /// Specifies the index of a positional argument **starting at** 1. /// + ///
+ /// /// **NOTE:** The index refers to position according to **other positional argument**. It does /// not define position in the argument list as a whole. /// + ///
+ /// + ///
+ /// /// **NOTE:** You can optionally leave off the `index` method, and the index will be /// assigned in order of evaluation. Utilizing the `index` method allows for setting /// indexes out of order /// + ///
+ /// + ///
+ /// /// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used /// with [`Arg::short`] or [`Arg::long`]. /// + ///
+ /// + ///
+ /// /// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument /// may be defined as having a variable number of arguments (i.e. with the highest index) /// + ///
+ /// /// # Panics /// /// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)` @@ -516,14 +540,26 @@ impl Arg { /// This is a "var arg" and everything that follows should be captured by it, as if the user had /// used a `--`. /// + ///
+ /// /// **NOTE:** To start the trailing "var arg" on unknown flags (and not just a positional /// value), set [`allow_hyphen_values`][Arg::allow_hyphen_values]. Either way, users still /// have the option to explicitly escape ambiguous arguments with `--`. /// + ///
+ /// + ///
+ /// /// **NOTE:** [`Arg::value_delimiter`] still applies if set. /// + ///
+ /// + ///
+ /// /// **NOTE:** Setting this requires [`Arg::num_args(..)`]. /// + ///
+ /// /// # Examples /// /// ```rust @@ -554,22 +590,42 @@ impl Arg { /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with /// the `--` syntax is otherwise not possible. /// + ///
+ /// /// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- ]` if /// `ARG` is marked as `.last(true)`. /// + ///
+ /// + ///
+ /// /// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing /// to set this can make the usage string very confusing. /// + ///
+ /// + ///
+ /// /// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS /// + ///
+ /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// - /// **CAUTION:** Using this setting *and* having child subcommands is not + ///
+ /// + ///
+ /// + /// **WARNING:** Using this setting *and* having child subcommands is not /// recommended with the exception of *also* using /// [`crate::Command::args_conflicts_with_subcommands`] /// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also /// marked [`Arg::required`]) /// + ///
+ /// /// # Examples /// /// ```rust @@ -704,8 +760,12 @@ impl Arg { /// /// i.e. when using this argument, the following argument *must* be present. /// + ///
+ /// /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// + ///
+ /// /// # Examples /// /// ```rust @@ -812,11 +872,15 @@ impl Arg { /// Specifies that an argument can be matched to all child [`Subcommand`]s. /// + ///
+ /// /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however /// their values once a user uses them will be propagated back up to parents. In effect, this /// means one should *define* all global arguments at the top level, however it doesn't matter /// where the user *uses* the global argument. /// + ///
+ /// /// # Examples /// /// Assume an application with two subcommands, and you'd like to define a @@ -994,6 +1058,8 @@ impl Arg { /// - Using an equals and no space such as `-o=value` or `--option=value` /// - Use a short and no space such as `-ovalue` /// + ///
+ /// /// **WARNING:** /// /// Setting a variable number of values (e.g. `1..=10`) for an argument without @@ -1012,6 +1078,8 @@ impl Arg { /// - Require a flag occurrence per value with [`ArgAction::Append`] /// - Require positional arguments to appear after `--` with [`Arg::last`] /// + ///
+ /// /// # Examples /// /// Option: @@ -1155,8 +1223,12 @@ impl Arg { /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to /// use all capital letters for the value name. /// + ///
+ /// /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] /// + ///
+ /// /// # Examples /// /// ```rust @@ -1218,11 +1290,19 @@ impl Arg { /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to /// use all capital letters for the value name. /// - /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or + ///
+ /// + /// **TIP:** It may help to use [`Arg::next_line_help(true)`] if there are long, or /// multiple value names in order to not throw off the help text alignment of all options. /// + ///
+ /// + ///
+ /// /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`]. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1273,8 +1353,12 @@ impl Arg { /// /// See [`ValueHint`] for more information. /// + ///
+ /// /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]. /// + ///
+ /// /// For example, to take a username as argument: /// /// ```rust @@ -1322,10 +1406,18 @@ impl Arg { /// [`Arg::required_if_eq_all`] is case-insensitive. /// /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// + ///
+ /// + ///
+ /// /// **NOTE:** To do unicode case folding, enable the `unicode` feature flag. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1381,18 +1473,30 @@ impl Arg { /// /// See also [`trailing_var_arg`][Arg::trailing_var_arg]. /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// + ///
+ /// + ///
+ /// /// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known /// flags but known flags get precedence over the next possible positional argument with /// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`], /// [`Arg::value_terminator`] is one way to ensure processing stops. /// + ///
+ /// + ///
+ /// /// **WARNING**: Take caution when using this setting combined with another argument using /// [`Arg::num_args`], as this becomes ambiguous `$ prog --arg -- -- val`. All /// three `--, --, val` will be values when the user may have thought the second `--` would /// constitute the normal, "Only positional args follow" idiom. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1443,8 +1547,12 @@ impl Arg { /// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers, /// all other undefined leading hyphens will fail to parse. /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// + ///
+ /// /// # Examples /// /// ```rust @@ -1472,8 +1580,12 @@ impl Arg { /// /// i.e. an equals between the option and associated value. /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// + ///
+ /// /// # Examples /// /// Setting `require_equals` requires that the option have an equals sign between @@ -1573,11 +1685,19 @@ impl Arg { /// argument until it reaches another valid argument, or one of the other more specific settings /// for multiple values is used (such as [`num_args`]). /// + ///
+ /// /// **NOTE:** This setting only applies to [options] and [positional arguments] /// + ///
+ /// + ///
+ /// /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one /// of the values /// + ///
+ /// /// # Examples /// /// ```rust @@ -1636,7 +1756,12 @@ impl Arg { /// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`] /// may be more appropriate. /// + ///
+ /// /// **NOTE:** Implicitly sets [`Arg::action(ArgAction::Set)`] [`Arg::num_args(1..)`], + /// + ///
+ /// /// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`. /// /// [`Arg::action(ArgAction::Set)`]: Arg::action() @@ -1654,10 +1779,18 @@ impl Arg { /// Value for the argument when not present. /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + ///
+ /// /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will /// still return `true`. If you wish to determine whether the argument was used at runtime or /// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source]. /// + ///
+ /// + ///
+ /// /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg /// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided @@ -1666,7 +1799,7 @@ impl Arg { /// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value` /// will be applied. /// - /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + ///
/// /// # Examples /// @@ -1760,12 +1893,16 @@ impl Arg { /// argument is a common example. By supplying a default, such as `default_missing_value("always")`, /// the user can quickly just add `--color` to the command line to produce the desired color output. /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + ///
+ /// /// **NOTE:** using this configuration option requires the use of the /// [`.num_args(0..N)`][Arg::num_args] and the /// [`.require_equals(true)`][Arg::require_equals] configuration option. These are required in /// order to unambiguously determine what, if any, value was supplied for the argument. /// - /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + ///
/// /// # Examples /// @@ -2080,8 +2217,12 @@ impl Arg { /// /// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`. /// + ///
+ /// /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise /// + ///
+ /// /// # Examples /// /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to @@ -2132,8 +2273,12 @@ impl Arg { /// /// If [`Arg::help`] is not specified, this message will be displayed for `-h`. /// + ///
+ /// /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise /// + ///
+ /// /// # Examples /// /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to @@ -2201,9 +2346,13 @@ impl Arg { /// /// To change, see [`Command::next_display_order`][crate::Command::next_display_order]. /// + ///
+ /// /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in /// [index] order. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2271,9 +2420,13 @@ impl Arg { /// This can be helpful for arguments with very long or complex help messages. /// This can also be helpful for arguments with very long flag names, or many/long value names. /// + ///
+ /// /// **NOTE:** To apply this setting to all arguments and subcommands, consider using /// [`crate::Command::next_line_help`] /// + ///
+ /// /// # Examples /// /// ```rust @@ -2323,8 +2476,12 @@ impl Arg { /// Do not display the argument in help message. /// + ///
+ /// /// **NOTE:** This does **not** hide the argument from usage strings on error /// + ///
+ /// /// # Examples /// /// Setting `Hidden` will hide the argument when displaying help text @@ -2370,11 +2527,15 @@ impl Arg { /// This is useful for args with many values, or ones which are explained elsewhere in the /// help text. /// - /// **NOTE:** Setting this requires [taking values][Arg::num_args] - /// /// To set this for all arguments, see /// [`Command::hide_possible_values`][crate::Command::hide_possible_values]. /// + ///
+ /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + ///
+ /// /// # Examples /// /// ```rust @@ -2403,8 +2564,12 @@ impl Arg { /// /// This is useful when default behavior of an arg is explained elsewhere in the help text. /// + ///
+ /// /// **NOTE:** Setting this requires [taking values][Arg::num_args] /// + ///
+ /// /// # Examples /// /// ```rust @@ -2494,11 +2659,19 @@ impl Arg { /// Hides an argument from short help (`-h`). /// + ///
+ /// /// **NOTE:** This does **not** hide the argument from usage strings on error /// + ///
+ /// + ///
+ /// /// **NOTE:** Setting this option will cause next-line-help output style to be used /// when long help (`--help`) is called. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2578,11 +2751,19 @@ impl Arg { /// Hides an argument from long help (`--help`). /// + ///
+ /// /// **NOTE:** This does **not** hide the argument from usage strings on error /// + ///
+ /// + ///
+ /// /// **NOTE:** Setting this option will cause next-line-help output style to be used /// when long help (`--help`) is called. /// + ///
+ /// /// # Examples /// /// Setting `hide_long_help(true)` will hide the argument when displaying long help text @@ -2749,6 +2930,10 @@ impl Arg { /// /// If `default` is set to `None`, `default_value` will be removed. /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + ///
+ /// /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg /// at runtime. This setting however only takes effect when the user has not provided a value at @@ -2756,7 +2941,7 @@ impl Arg { /// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were /// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied. /// - /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + ///
/// /// # Examples /// @@ -2894,10 +3079,14 @@ impl Arg { /// /// The method takes a slice of tuples in the `(arg, predicate, default)` format. /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + ///
+ /// /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first /// if multiple conditions are true, the first one found will be applied and the ultimate value. /// - /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + ///
/// /// # Examples /// @@ -3014,9 +3203,13 @@ impl Arg { /// Set this arg as [required] as long as the specified argument is not present at runtime. /// - /// **Pro Tip:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not + ///
+ /// + /// **TIP:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not /// mandatory to also set. /// + ///
+ /// /// # Examples /// /// ```rust @@ -3084,9 +3277,13 @@ impl Arg { /// * supplies the `self` arg. /// * supplies *all* of the `names` arguments. /// + ///
+ /// /// **NOTE:** If you wish for this argument to only be required unless *any of* these args are /// present see [`Arg::required_unless_present_any`] /// + ///
+ /// /// # Examples /// /// ```rust @@ -3163,9 +3360,13 @@ impl Arg { /// * supplies the `self` arg. /// * supplies *one or more* of the `unless` arguments. /// + ///
+ /// /// **NOTE:** If you wish for this argument to be required unless *all of* these args are /// present see [`Arg::required_unless_present_all`] /// + ///
+ /// /// # Examples /// /// ```rust @@ -3653,19 +3854,39 @@ impl Arg { /// This argument is mutually exclusive with the specified argument. /// + ///
+ /// /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules /// only need to be set for one of the two arguments, they do not need to be set for each. /// + ///
+ /// + ///
+ /// /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments /// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not /// need to also do `B.conflicts_with(A)`) /// + ///
+ /// + ///
+ /// /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument. /// + ///
+ /// + ///
+ /// /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// + ///
+ /// + ///
+ /// /// **NOTE:** All arguments implicitly conflict with themselves. /// + ///
+ /// /// # Examples /// /// ```rust @@ -3713,15 +3934,27 @@ impl Arg { /// /// See [`Arg::conflicts_with`]. /// + ///
+ /// /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules /// only need to be set for one of the two arguments, they do not need to be set for each. /// + ///
+ /// + ///
+ /// /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments /// (i.e. if A conflicts with B, defining `A.conflicts_with(B)` is sufficient. You do not need /// need to also do `B.conflicts_with(A)`) /// + ///
+ /// + ///
+ /// /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// + ///
+ /// /// # Examples /// /// ```rust @@ -3767,11 +4000,19 @@ impl Arg { /// will override each other in POSIX style (whichever argument was specified at runtime /// **last** "wins") /// + ///
+ /// /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed /// + ///
+ /// + ///
+ /// /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`]. /// + ///
+ /// /// # Examples /// /// ```rust @@ -3807,11 +4048,19 @@ impl Arg { /// i.e. this argument and the following argument will override each other in POSIX style /// (whichever argument was specified at runtime **last** "wins") /// + ///
+ /// /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed /// + ///
+ /// + ///
+ /// /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`]. /// + ///
+ /// /// # Examples /// /// ```rust diff --git a/clap_builder/src/builder/arg_group.rs b/clap_builder/src/builder/arg_group.rs index d92f3d99..2c07ce4b 100644 --- a/clap_builder/src/builder/arg_group.rs +++ b/clap_builder/src/builder/arg_group.rs @@ -289,14 +289,22 @@ impl ArgGroup { /// This is unless conflicting with another argument. A required group will be displayed in /// the usage string of the application in the format ``. /// + ///
+ /// /// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not /// globally. /// + ///
+ /// + ///
+ /// /// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with /// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group. /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which /// states, '*At least* one arg from this group must be used. Using multiple is OK." /// + ///
+ /// /// # Examples /// /// ```rust @@ -335,8 +343,12 @@ impl ArgGroup { /// [argument requirement rules], you can name other arguments or groups that must be present /// when any one of the arguments from this group is used. /// + ///
+ /// /// **NOTE:** The name provided may be an argument or group name /// + ///
+ /// /// # Examples /// /// ```rust @@ -380,8 +392,12 @@ impl ArgGroup { /// [argument requirement rules], you can name other arguments or groups that must be present /// when one of the arguments from this group is used. /// + ///
+ /// /// **NOTE:** The names provided may be an argument or group name /// + ///
+ /// /// # Examples /// /// ```rust @@ -426,8 +442,12 @@ impl ArgGroup { /// other arguments or groups that must *not* be present when one of the arguments from this /// group are used. /// + ///
+ /// /// **NOTE:** The name provided may be an argument, or group name /// + ///
+ /// /// # Examples /// /// ```rust @@ -468,8 +488,12 @@ impl ArgGroup { /// Exclusion rules function just like [argument exclusion rules], you can name other arguments /// or groups that must *not* be present when one of the arguments from this group are used. /// + ///
+ /// /// **NOTE:** The names provided may be an argument, or group name /// + ///
+ /// /// # Examples /// /// ```rust diff --git a/clap_builder/src/builder/command.rs b/clap_builder/src/builder/command.rs index 6472071f..0bdb6a74 100644 --- a/clap_builder/src/builder/command.rs +++ b/clap_builder/src/builder/command.rs @@ -640,11 +640,15 @@ impl Command { /// Parse [`env::args_os`], returning a [`clap::Result`] on failure. /// + ///
+ /// /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// used. It will return a [`clap::Error`], where the [`kind`] is a /// [`ErrorKind::DisplayHelp`] or [`ErrorKind::DisplayVersion`] respectively. You must call /// [`Error::exit`] or perform a [`std::process::exit`]. /// + ///
+ /// /// # Panics /// /// If contradictory arguments or settings exist (debug builds). @@ -675,9 +679,13 @@ impl Command { /// Parse the specified arguments, [exiting][Error::exit] on failure. /// + ///
+ /// /// **NOTE:** The first argument will be parsed as the binary name unless /// [`Command::no_binary_name`] is used. /// + ///
+ /// /// # Panics /// /// If contradictory arguments or settings exist (debug builds). @@ -709,14 +717,22 @@ impl Command { /// Parse the specified arguments, returning a [`clap::Result`] on failure. /// + ///
+ /// /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or /// perform a [`std::process::exit`] yourself. /// + ///
+ /// + ///
+ /// /// **NOTE:** The first argument will be parsed as the binary name unless /// [`Command::no_binary_name`] is used. /// + ///
+ /// /// # Panics /// /// If contradictory arguments or settings exist (debug builds). @@ -755,14 +771,22 @@ impl Command { /// /// Like [`Command::try_get_matches_from`] but doesn't consume the `Command`. /// + ///
+ /// /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or /// perform a [`std::process::exit`] yourself. /// + ///
+ /// + ///
+ /// /// **NOTE:** The first argument will be parsed as the binary name unless /// [`Command::no_binary_name`] is used. /// + ///
+ /// /// # Panics /// /// If contradictory arguments or settings exist (debug builds). @@ -1087,8 +1111,12 @@ impl Command { /// Try not to fail on parse errors, like missing option values. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1125,8 +1153,12 @@ impl Command { /// This is the equivalent to saying the `foo` arg using [`Arg::overrides_with("foo")`] for all /// defined arguments. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with() #[inline] pub fn args_override_self(self, yes: bool) -> Self { @@ -1140,12 +1172,20 @@ impl Command { /// Disables the automatic delimiting of values after `--` or when [`Arg::trailing_var_arg`] /// was used. /// + ///
+ /// /// **NOTE:** The same thing can be done manually by setting the final positional argument to /// [`Arg::value_delimiter(None)`]. Using this setting is safer, because it's easier to locate /// when making changes. /// + ///
+ /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1170,10 +1210,18 @@ impl Command { /// /// To customize how the output is styled, see [`Command::styles`]. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// + ///
+ /// /// **NOTE:** Default behaviour is [`ColorChoice::Auto`]. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1201,10 +1249,18 @@ impl Command { /// Sets the [`Styles`] for terminal output /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// + ///
+ /// /// **NOTE:** Default behaviour is [`Styles::default`]. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1237,10 +1293,18 @@ impl Command { /// **`unstable-v5` feature**: Defaults to unbound, being subject to /// [`Command::max_term_width`]. /// + ///
+ /// /// **NOTE:** This setting applies globally and *not* on a per-command basis. /// + ///
+ /// + ///
+ /// /// **NOTE:** This requires the `wrap_help` feature /// + ///
+ /// /// # Examples /// /// ```rust @@ -1267,10 +1331,18 @@ impl Command { /// /// **`unstable-v5` feature**: Defaults to 100. /// + ///
+ /// /// **NOTE:** This setting applies globally and *not* on a per-command basis. /// + ///
+ /// + ///
+ /// /// **NOTE:** This requires the `wrap_help` feature /// + ///
+ /// /// # Examples /// /// ```rust @@ -1345,8 +1417,12 @@ impl Command { /// /// Defaults to `false`; subcommands have independent version strings from their parents. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1373,8 +1449,12 @@ impl Command { /// Places the help string for all arguments and subcommands on the line after them. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1395,8 +1475,12 @@ impl Command { /// Disables `-h` and `--help` flag. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1450,8 +1534,12 @@ impl Command { /// Disables the `help` [`subcommand`]. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1481,8 +1569,12 @@ impl Command { /// Disables colorized help messages. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1503,11 +1595,19 @@ impl Command { /// Panic if help descriptions are omitted. /// + ///
+ /// /// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at /// compile-time with `#![deny(missing_docs)]` /// + ///
+ /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1563,7 +1663,11 @@ impl Command { /// To set this per argument, see /// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values]. /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. + /// + ///
#[inline] pub fn hide_possible_values(self, yes: bool) -> Self { if yes { @@ -1578,12 +1682,20 @@ impl Command { /// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and /// `--test`. /// + ///
+ /// /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match /// `--te` to `--test` there could not also be another argument or alias `--temp` because both /// start with `--te` /// + ///
+ /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// [aliases]: crate::Command::aliases() #[inline] pub fn infer_long_args(self, yes: bool) -> Self { @@ -1599,17 +1711,29 @@ impl Command { /// For example, to match a subcommand named `test`, one could use `t`, `te`, `tes`, and /// `test`. /// + ///
+ /// /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match `te` /// to `test` there could not also be a subcommand or alias `temp` because both start with `te` /// - /// **CAUTION:** This setting can interfere with [positional/free arguments], take care when + ///
+ /// + ///
+ /// + /// **WARNING:** This setting can interfere with [positional/free arguments], take care when /// designing CLIs which allow inferred subcommands and have potential positional/free /// arguments whose values could start with the same characters as subcommands. If this is the /// case, it's recommended to use settings such as [`Command::args_conflicts_with_subcommands`] in /// conjunction with this setting. /// + ///
+ /// + ///
+ /// /// **NOTE:** This choice is propagated to all child subcommands. /// + ///
+ /// /// # Examples /// /// ```no_run @@ -1664,13 +1788,21 @@ impl Command { /// This should only be used when absolutely necessary, such as when the binary name for your /// application is misleading, or perhaps *not* how the user should invoke your program. /// - /// **Pro-tip:** When building things such as third party `cargo` + ///
+ /// + /// **TIP:** When building things such as third party `cargo` /// subcommands, this setting **should** be used! /// + ///
+ /// + ///
+ /// /// **NOTE:** This *does not* change or set the name of the binary file on /// disk. It only changes what clap thinks the name is for the purposes of /// error or help messages. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1705,13 +1837,21 @@ impl Command { /// Sets the author(s) for the help message. /// - /// **Pro-tip:** Use `clap`s convenience macro [`crate_authors!`] to + ///
+ /// + /// **TIP:** Use `clap`s convenience macro [`crate_authors!`] to /// automatically set your application's author(s) to the same thing as your /// crate at compile time. /// + ///
+ /// + ///
+ /// /// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show /// up. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1731,9 +1871,6 @@ impl Command { /// /// If [`Command::long_about`] is not specified, this message will be displayed for `--help`. /// - /// **NOTE:** Only `Command::about` (short format) is used in completion - /// script generation in order to be concise. - /// /// See also [`crate_description!`](crate::crate_description!). /// /// # Examples @@ -1756,9 +1893,13 @@ impl Command { /// If not set, [`Command::about`] will be used for long help in addition to short help /// (`-h`). /// + ///
+ /// /// **NOTE:** Only [`Command::about`] (short format) is used in completion /// script generation in order to be concise. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1872,10 +2013,14 @@ impl Command { /// /// If [`Command::long_version`] is not specified, this message will be displayed for `--version`. /// - /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to + ///
+ /// + /// **TIP:** Use `clap`s convenience macro [`crate_version!`] to /// automatically set your application's version to the same thing as your /// crate at compile time. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1895,10 +2040,14 @@ impl Command { /// /// If [`Command::version`] is not specified, this message will be displayed for `-V`. /// - /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to + ///
+ /// + /// **TIP:** Use `clap`s convenience macro [`crate_version!`] to /// automatically set your application's version to the same thing as your /// crate at compile time. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1921,10 +2070,16 @@ impl Command { /// Overrides the `clap` generated usage string for help and error messages. /// + ///
+ /// /// **NOTE:** Using this setting disables `clap`s "context-aware" usage /// strings. After this setting is set, this will be *the only* usage string /// displayed to the user! /// + ///
+ /// + ///
+ /// /// **NOTE:** Multiple usage lines may be present in the usage argument, but /// some rules need to be followed to ensure the usage lines are formatted /// correctly by the default help formatter: @@ -1933,6 +2088,8 @@ impl Command { /// - Indent all subsequent usage lines with seven spaces. /// - The last line must not end with a newline. /// + ///
+ /// /// # Examples /// /// ```rust @@ -1968,11 +2125,15 @@ impl Command { /// /// This should only be used when the auto-generated message does not suffice. /// + ///
+ /// /// **NOTE:** This **only** replaces the help message for the current /// command, meaning if you are using subcommands, those help messages will /// still be auto-generated unless you specify a [`Command::override_help`] for /// them as well. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2004,9 +2165,6 @@ impl Command { /// Sets the help template to be used, overriding the default format. /// - /// **NOTE:** The template system is by design very simple. Therefore, the - /// tags have to be written in the lowercase and without spacing. - /// /// Tags are given inside curly brackets. /// /// Valid tags are: @@ -2149,8 +2307,12 @@ impl Command { /// Exit gracefully if no arguments are present (e.g. `$ myprog`). /// + ///
+ /// /// **NOTE:** [`subcommands`] count as arguments /// + ///
+ /// /// # Examples /// /// ```rust @@ -2369,8 +2531,12 @@ impl Command { /// /// Allows the subcommand to be used as if it were an [`Arg::long`]. /// + ///
+ /// /// **NOTE:** Any leading `-` characters will be stripped. /// + ///
+ /// /// # Examples /// /// To set `long_flag` use a word containing valid UTF-8 codepoints. If you supply a double leading @@ -2410,14 +2576,22 @@ impl Command { /// alias. This is more efficient and easier than creating multiple hidden subcommands as one /// only needs to check for the existence of this command, and not all aliased variants. /// + ///
+ /// /// **NOTE:** Aliases defined with this method are *hidden* from the help /// message. If you're looking for aliases that will be displayed in the help /// message, see [`Command::visible_alias`]. /// + ///
+ /// + ///
+ /// /// **NOTE:** When using aliases and checking for the existence of a /// particular subcommand within an [`ArgMatches`] struct, one only needs to /// search for the original name and not all aliases. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2501,14 +2675,22 @@ impl Command { /// given aliases. This is more efficient, and easier than creating multiple hidden subcommands /// as one only needs to check for the existence of this command and not all aliased variants. /// + ///
+ /// /// **NOTE:** Aliases defined with this method are *hidden* from the help /// message. If looking for aliases that will be displayed in the help /// message, see [`Command::visible_aliases`]. /// + ///
+ /// + ///
+ /// /// **NOTE:** When using aliases and checking for the existence of a /// particular subcommand within an [`ArgMatches`] struct, one only needs to /// search for the original name and not all aliases. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2595,15 +2777,23 @@ impl Command { /// than creating hidden subcommands as one only needs to check for /// the existence of this command and not all aliased variants. /// + ///
+ /// /// **NOTE:** The alias defined with this method is *visible* from the help /// message and displayed as if it were just another regular subcommand. If /// looking for an alias that will not be displayed in the help message, see /// [`Command::alias`]. /// + ///
+ /// + ///
+ /// /// **NOTE:** When using aliases and checking for the existence of a /// particular subcommand within an [`ArgMatches`] struct, one only needs to /// search for the original name and not all aliases. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2694,15 +2884,23 @@ impl Command { /// than creating multiple hidden subcommands as one only needs to check for /// the existence of this command and not all aliased variants. /// + ///
+ /// /// **NOTE:** The alias defined with this method is *visible* from the help /// message and displayed as if it were just another regular subcommand. If /// looking for an alias that will not be displayed in the help message, see /// [`Command::alias`]. /// + ///
+ /// + ///
+ /// /// **NOTE:** When using aliases, and checking for the existence of a /// particular subcommand within an [`ArgMatches`] struct, one only needs to /// search for the original name and not all aliases. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2881,14 +3079,22 @@ impl Command { /// /// Arguments will be stored in the `""` argument in the [`ArgMatches`] /// + ///
+ /// /// **NOTE:** Use this setting with caution, /// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand) /// will **not** cause an error and instead be treated as a potential subcommand. /// One should check for such cases manually and inform the user appropriately. /// + ///
+ /// + ///
+ /// /// **NOTE:** A built-in subcommand will be parsed as an external subcommand when escaped with /// `--`. /// + ///
+ /// /// # Examples /// /// ```rust @@ -2930,8 +3136,12 @@ impl Command { /// The default parser is for `OsString`. This can be used to switch it to `String` or another /// type. /// + ///
+ /// /// **NOTE:** Setting this requires [`Command::allow_external_subcommands`] /// + ///
+ /// /// # Examples /// /// ```rust @@ -3090,8 +3300,12 @@ impl Command { /// using this setting would allow you to set those arguments to [`Arg::required(true)`] /// and yet receive no error so long as the user uses a valid subcommand instead. /// + ///
+ /// /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) /// + ///
+ /// /// # Examples /// /// This first example shows that it is an error to not use a required argument @@ -3171,15 +3385,27 @@ impl Command { /// [`allow_external_subcommands`][Command::allow_external_subcommands] if you want to specifically /// get the unrecognized binary name. /// + ///
+ /// /// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret /// the command name in incompatible ways. /// + ///
+ /// + ///
+ /// /// **NOTE:** The multicall command cannot have arguments. /// + ///
+ /// + ///
+ /// /// **NOTE:** Applets are slightly semantically different from subcommands, /// so it's recommended to use [`Command::subcommand_help_heading`] and /// [`Command::subcommand_value_name`] to change the descriptive text as above. /// + ///
+ /// /// # Examples /// /// `hostname` is an example of a multicall executable. @@ -3744,15 +3970,15 @@ impl Command { } } - // Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with. - // - // This behavior follows the propagation rules of global arguments. - // It is useful for finding conflicts for arguments declared as global. - // - // ### Panics - // - // If the given arg contains a conflict with an argument that is unknown to - // this `Command`. + /// Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with. + /// + /// This behavior follows the propagation rules of global arguments. + /// It is useful for finding conflicts for arguments declared as global. + /// + /// ### Panics + /// + /// If the given arg contains a conflict with an argument that is unknown to + /// this `Command`. fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator { arg.blacklist @@ -3774,19 +4000,24 @@ impl Command { .collect() } - // Get a list of subcommands which contain the provided Argument - // - // This command will only include subcommands in its list for which the subcommands - // parent also contains the Argument. - // - // This search follows the propagation rules of global arguments. - // It is useful to finding subcommands, that have inherited a global argument. - // - // **NOTE:** In this case only Sucommand_1 will be included - // Subcommand_1 (contains Arg) - // Subcommand_1.1 (doesn't contain Arg) - // Subcommand_1.1.1 (contains Arg) - // + /// Get a list of subcommands which contain the provided Argument + /// + /// This command will only include subcommands in its list for which the subcommands + /// parent also contains the Argument. + /// + /// This search follows the propagation rules of global arguments. + /// It is useful to finding subcommands, that have inherited a global argument. + /// + ///
+ /// + /// **NOTE:** In this case only `Sucommand_1` will be included + /// ```text + /// Subcommand_1 (contains Arg) + /// Subcommand_1.1 (doesn't contain Arg) + /// Subcommand_1.1.1 (contains Arg) + /// ``` + /// + ///
fn get_subcommands_containing(&self, arg: &Arg) -> Vec<&Self> { let mut vec = Vec::new(); for idx in 0..self.subcommands.len() { diff --git a/clap_builder/src/builder/os_str.rs b/clap_builder/src/builder/os_str.rs index 5f3d9cde..a42066e1 100644 --- a/clap_builder/src/builder/os_str.rs +++ b/clap_builder/src/builder/os_str.rs @@ -2,8 +2,12 @@ use crate::builder::Str; /// A UTF-8-encoded fixed string /// +///
+/// /// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string` /// feature +/// +///
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] pub struct OsStr { name: Inner, diff --git a/clap_builder/src/builder/possible_value.rs b/clap_builder/src/builder/possible_value.rs index ef931b49..757dc36c 100644 --- a/clap_builder/src/builder/possible_value.rs +++ b/clap_builder/src/builder/possible_value.rs @@ -9,10 +9,14 @@ use crate::util::eq_ignore_case; /// /// See also [`PossibleValuesParser`][crate::builder::PossibleValuesParser] /// +///
+/// /// **NOTE:** Most likely you can use strings, rather than `PossibleValue` as it is only required /// to [hide] single values from help messages and shell completions or to attach [help] to /// possible values. /// +///
+/// /// # Examples /// /// ```rust @@ -45,9 +49,13 @@ impl PossibleValue { /// /// The name will be used to decide whether this value was provided by the user to an argument. /// + ///
+ /// /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments /// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`]. /// + ///
+ /// /// # Examples /// /// ```rust diff --git a/clap_builder/src/builder/str.rs b/clap_builder/src/builder/str.rs index a210d0ac..b812def4 100644 --- a/clap_builder/src/builder/str.rs +++ b/clap_builder/src/builder/str.rs @@ -1,7 +1,11 @@ /// A UTF-8-encoded fixed string /// +///
+/// /// **NOTE:** To support dynamic values (i.e. `String`), enable the `string` /// feature +/// +///
#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] pub struct Str { name: Inner, diff --git a/clap_builder/src/builder/value_parser.rs b/clap_builder/src/builder/value_parser.rs index ffa174f3..f171db8a 100644 --- a/clap_builder/src/builder/value_parser.rs +++ b/clap_builder/src/builder/value_parser.rs @@ -1267,10 +1267,14 @@ where /// Parse number that fall within a range of values /// +///
+/// /// **NOTE:** To capture negative values, you will also need to set /// [`Arg::allow_negative_numbers`][crate::Arg::allow_negative_numbers] or /// [`Arg::allow_hyphen_values`][crate::Arg::allow_hyphen_values]. /// +///
+/// /// # Example /// /// Usage: diff --git a/clap_builder/src/derive.rs b/clap_builder/src/derive.rs index 28d56abd..06a94015 100644 --- a/clap_builder/src/derive.rs +++ b/clap_builder/src/derive.rs @@ -20,7 +20,11 @@ use std::ffi::OsString; /// /// See also [`Subcommand`] and [`Args`]. /// +///
+/// /// **NOTE:** Deriving requires the `derive` feature flag +/// +///
pub trait Parser: FromArgMatches + CommandFactory + Sized { /// Parse from `std::env::args_os()`, [exit][Error::exit] on error. fn parse() -> Self { @@ -214,7 +218,11 @@ pub trait FromArgMatches: Sized { /// `Args`. /// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`. /// +///
+/// /// **NOTE:** Deriving requires the `derive` feature flag +/// +///
pub trait Args: FromArgMatches + Sized { /// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments fn group_id() -> Option { @@ -245,7 +253,11 @@ pub trait Args: FromArgMatches + Sized { /// - `#[command(flatten)] Variant(SubCmd)`: Attribute can only be used with enum variants that impl /// `Subcommand`. /// +///
+/// /// **NOTE:** Deriving requires the `derive` feature flag +/// +///
pub trait Subcommand: FromArgMatches + Sized { /// Append to [`Command`] so it can instantiate `Self` via /// [`FromArgMatches::from_arg_matches_mut`] @@ -272,7 +284,11 @@ pub trait Subcommand: FromArgMatches + Sized { /// - Call [`EnumValueParser`][crate::builder::EnumValueParser] /// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`. /// +///
+/// /// **NOTE:** Deriving requires the `derive` feature flag +/// +///
pub trait ValueEnum: Sized + Clone { /// All possible argument values, in display order. fn value_variants<'a>() -> &'a [Self]; diff --git a/clap_builder/src/error/format.rs b/clap_builder/src/error/format.rs index 7114d5fe..5126ea56 100644 --- a/clap_builder/src/error/format.rs +++ b/clap_builder/src/error/format.rs @@ -26,8 +26,12 @@ pub trait ErrorFormatter: Sized { /// /// No context is included. /// +///
+/// /// **NOTE:** Consider removing the `error-context` default feature if using this to remove all /// overhead for [`RichFormatter`]. +/// +///
#[non_exhaustive] pub struct KindFormatter; diff --git a/clap_builder/src/macros.rs b/clap_builder/src/macros.rs index 83db012e..c03d3237 100644 --- a/clap_builder/src/macros.rs +++ b/clap_builder/src/macros.rs @@ -79,12 +79,16 @@ macro_rules! crate_description { /// Allows you to pull the name from your Cargo.toml at compile time. /// +///
+/// /// **NOTE:** This macro extracts the name from an environment variable `CARGO_PKG_NAME`. /// When the crate name is set to something different from the package name, /// use environment variables `CARGO_CRATE_NAME` or `CARGO_BIN_NAME`. /// See [the Cargo Book](https://doc.rust-lang.org/cargo/reference/environment-variables.html) /// for more information. /// +///
+/// /// # Examples /// /// ```no_run @@ -104,6 +108,8 @@ macro_rules! crate_name { /// Allows you to build the `Command` instance from your Cargo.toml at compile time. /// +///
+/// /// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically, /// and therefore won't change the generated output until you recompile. /// @@ -111,6 +117,8 @@ macro_rules! crate_name { /// `Cargo.toml` is changed by including this in your `src/main.rs` file /// `include_str!("../Cargo.toml");` /// +///
+/// /// # Examples /// /// ```no_run @@ -430,9 +438,13 @@ macro_rules! arg_impl { /// /// Allows creation of basic settings for the [`Arg`]. /// +///
+/// /// **NOTE**: Not all settings may be set using the usage string method. Some properties are /// only available via the builder pattern. /// +///
+/// /// # Syntax /// /// Usage strings typically following the form: @@ -467,9 +479,13 @@ macro_rules! arg_impl { /// A long flag is a `--` followed by either a bare-word or a string, like `--foo` or /// `--"foo"`. /// +///
+/// /// **NOTE:** Dashes in the long name (e.g. `--foo-bar`) is not supported and quoting is required /// (e.g. `--"foo-bar"`). /// +///
+/// /// See [`Arg::long`][crate::Arg::long]. /// /// ### Values (Value Notation) diff --git a/clap_builder/src/parser/matches/arg_matches.rs b/clap_builder/src/parser/matches/arg_matches.rs index b44403f1..90fbb59f 100644 --- a/clap_builder/src/parser/matches/arg_matches.rs +++ b/clap_builder/src/parser/matches/arg_matches.rs @@ -83,9 +83,13 @@ impl ArgMatches { /// /// Returns `None` if the option wasn't present. /// + ///
+ /// /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// + ///
+ /// /// # Panic /// /// If the argument definition and access mismatch. To handle this case programmatically, see @@ -374,9 +378,13 @@ impl ArgMatches { /// /// Returns `None` if the option wasn't present. /// + ///
+ /// /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// + ///
+ /// /// # Panic /// /// If the argument definition and access mismatch. To handle this case programmatically, see @@ -485,9 +493,13 @@ impl ArgMatches { /// Check if values are present for the argument or group id /// + ///
+ /// /// *NOTE:* This will always return `true` if [`default_value`] has been set. /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. /// + ///
+ /// /// # Panics /// /// If `id` is not a valid argument or group name (debug builds). To handle this case programmatically, see @@ -612,9 +624,13 @@ impl ArgMatches { /// /// The examples should clear this up. /// + ///
+ /// /// *NOTE:* If an argument is allowed multiple times, this method will only give the *first* /// index. See [`ArgMatches::indices_of`]. /// + ///
+ /// /// # Panics /// /// If `id` is not a valid argument or group id (debug builds). @@ -760,9 +776,13 @@ impl ArgMatches { /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the /// index for `val` would be recorded. This is by design. /// + ///
+ /// /// *NOTE:* For more information about how clap indices compared to argv indices, see /// [`ArgMatches::index_of`] /// + ///
+ /// /// # Panics /// /// If `id` is not a valid argument or group id (debug builds). diff --git a/clap_builder/src/util/color.rs b/clap_builder/src/util/color.rs index f446c016..c1978a38 100644 --- a/clap_builder/src/util/color.rs +++ b/clap_builder/src/util/color.rs @@ -6,8 +6,12 @@ use crate::derive::ValueEnum; pub enum ColorChoice { /// Enables colored output only when the output is going to a terminal or TTY. /// + ///
+ /// /// **NOTE:** This is the default behavior of `clap`. /// + ///
+ /// /// # Examples /// /// ```rust diff --git a/clap_complete/src/aot/generator/mod.rs b/clap_complete/src/aot/generator/mod.rs index 7999c48b..856df087 100644 --- a/clap_complete/src/aot/generator/mod.rs +++ b/clap_complete/src/aot/generator/mod.rs @@ -68,9 +68,13 @@ pub trait Generator { /// Generate a completions file for a specified shell at compile-time. /// +///
+/// /// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a /// [`cargo-xtask`](https://github.com/matklad/cargo-xtask) /// +///
+/// /// # Examples /// /// The following example generates a bash completion script via a `build.rs` script. In this @@ -160,9 +164,13 @@ pub trait Generator { /// Assuming we compiled with debug mode, it would be somewhere similar to /// `/target/debug/build/myapp-/out/myapp.bash`. /// +///
+/// /// **NOTE:** Please look at the individual [shells][crate::shells] /// to see the name of the files generated. /// +///
+/// /// Using [`ValueEnum::value_variants()`][clap::ValueEnum::value_variants] you can easily loop over /// all the supported shell variants to generate all the completions at once too. /// diff --git a/clap_complete/src/aot/generator/utils.rs b/clap_complete/src/aot/generator/utils.rs index a9dd3173..da5a4d8a 100644 --- a/clap_complete/src/aot/generator/utils.rs +++ b/clap_complete/src/aot/generator/utils.rs @@ -18,7 +18,11 @@ pub fn all_subcommands(cmd: &Command) -> Vec<(String, String)> { /// Finds the subcommand [`clap::Command`] from the given [`clap::Command`] with the given path. /// +///
+/// /// **NOTE:** `path` should not contain the root `bin_name`. +/// +///
pub fn find_subcommand_with_path<'cmd>(p: &'cmd Command, path: Vec<&str>) -> &'cmd Command { let mut cmd = p; diff --git a/clap_complete/src/env/mod.rs b/clap_complete/src/env/mod.rs index 2c5049bd..9d7f59cf 100644 --- a/clap_complete/src/env/mod.rs +++ b/clap_complete/src/env/mod.rs @@ -24,6 +24,8 @@ //! //! To source your completions: //! +//!
+//! //! **WARNING:** We recommend re-sourcing your completions on upgrade. //! These completions work by generating shell code that calls into `your_program` while completing. //! That interface is unstable and a mismatch between the shell code and `your_program` may result @@ -31,6 +33,8 @@ //! For this reason, we recommend generating the shell code anew on shell startup so that it is //! "self-correcting" on shell launch, rather than writing the generated completions to a file. //! +//!
+//! //! Bash //! ```bash //! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc @@ -355,9 +359,13 @@ pub trait EnvCompleter { /// - `bin`: see [`CompleteEnv::bin`] /// - `completer`: see [`CompleteEnv::completer`] /// + ///
+ /// /// **WARNING:** There are no stability guarantees between the call to /// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`]. /// Caching the results of this call may result in invalid or no completions to be generated. + /// + ///
fn write_registration( &self, var: &str, diff --git a/clap_lex/src/lib.rs b/clap_lex/src/lib.rs index c6815085..c0ba47e3 100644 --- a/clap_lex/src/lib.rs +++ b/clap_lex/src/lib.rs @@ -133,8 +133,12 @@ pub struct RawArgs { impl RawArgs { //// Create an argument list to parse /// + ///
+ /// /// **NOTE:** The argument returned will be the current binary. /// + ///
+ /// /// # Example /// /// ```rust,no_run @@ -362,14 +366,22 @@ impl<'s> ParsedArg<'s> { /// Treat as a value /// + ///
+ /// /// **NOTE:** May return a flag or an escape. + /// + ///
pub fn to_value_os(&self) -> &OsStr { self.inner } /// Treat as a value /// + ///
+ /// /// **NOTE:** May return a flag or an escape. + /// + ///
pub fn to_value(&self) -> Result<&str, &OsStr> { self.inner.to_str().ok_or(self.inner) } diff --git a/examples/pacman.md b/examples/pacman.md index b02cf8f1..1b8e58d9 100644 --- a/examples/pacman.md +++ b/examples/pacman.md @@ -75,5 +75,9 @@ For more information, try '--help'. ``` +
+ **NOTE:** Keep in mind that subcommands, flags, and long flags are *case sensitive*: `-Q` and `-q` are different flags/subcommands. For example, you can have both `-Q` subcommand and `-q` flag, and they will be properly disambiguated. Let's make a quick program to illustrate. + +
diff --git a/src/_derive/mod.rs b/src/_derive/mod.rs index b1c0b217..a1a1d671 100644 --- a/src/_derive/mod.rs +++ b/src/_derive/mod.rs @@ -126,10 +126,14 @@ //! magic attributes documentation for details. This allows users to access the //! raw behavior of an attribute via `()` syntax. //! +//!
+//! //! **NOTE:** Some attributes are inferred from [Arg Types](#arg-types) and [Doc //! Comments](#doc-comments). Explicit attributes take precedence over inferred //! attributes. //! +//!
+//! //! ### Command Attributes //! //! These correspond to a [`Command`][crate::Command] which is used for both top-level parsers and @@ -349,6 +353,8 @@ //! } //! ``` //! +//!
+//! //! **NOTE:** Attributes have priority over doc comments! //! //! **Top level doc comments always generate `Command::about/long_about` calls!** @@ -357,6 +363,8 @@ //! the doc comment. To clear `long_about`, you can use //! `#[command(long_about = None)]`. //! +//!
+//! //! ### Pre-processing //! //! ```rust