From 01055fb796ef5af243ccf7ac219a4f90c043dfd9 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Sat, 16 Oct 2021 13:35:53 -0500 Subject: [PATCH 1/2] docs(yaml): Consistently place layout descriptio --- src/build/arg/mod.rs | 122 +++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index ae798527..af1d0e18 100644 --- a/src/build/arg/mod.rs +++ b/src/build/arg/mod.rs @@ -1143,7 +1143,8 @@ impl<'help> Arg<'help> { /// .exclusive(true) /// # ; /// ``` - /// **NOTE:** If using YAML the above example should be laid out as follows + /// + /// If using YAML the above example should be laid out as follows /// /// ```yaml /// - config @@ -1388,13 +1389,6 @@ impl<'help> Arg<'help> { /// if this arg (`self`) is present and its value equals to `val`. /// If it does, `another_arg` will be marked as required. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// requires_if: - /// - [val, arg] - /// ``` - /// /// # Examples /// /// ```rust @@ -1404,6 +1398,13 @@ impl<'help> Arg<'help> { /// # ; /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// requires_if: + /// - [val, arg] + /// ``` + /// /// Setting `Arg::requires_if(val, arg)` requires that the `arg` be used at runtime if the /// defining argument's value is equal to `val`. If the defining argument is anything other than /// `val`, the other argument isn't required. @@ -1452,14 +1453,6 @@ impl<'help> Arg<'help> { /// Allows multiple conditional requirements. The requirement will only become valid if this arg's value /// equals `val`. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// requires_if: - /// - [val, arg] - /// - [val2, arg2] - /// ``` - /// /// # Examples /// /// ```rust @@ -1472,6 +1465,14 @@ impl<'help> Arg<'help> { /// # ; /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// requires_if: + /// - [val, arg] + /// - [val2, arg2] + /// ``` + /// /// Setting `Arg::requires_ifs(&["val", "arg"])` requires that the `arg` be used at runtime if the /// defining argument's value is equal to `val`. If the defining argument's value is anything other /// than `val`, `arg` isn't required. @@ -1509,13 +1510,6 @@ impl<'help> Arg<'help> { /// Allows specifying that this argument is [required] only if the specified /// `arg` is present at runtime and its value equals `val`. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// required_if_eq: - /// - [arg, val] - /// ``` - /// /// # Examples /// /// ```rust @@ -1525,6 +1519,13 @@ impl<'help> Arg<'help> { /// # ; /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// required_if_eq: + /// - [arg, val] + /// ``` + /// /// ```rust /// # use clap::{App, Arg, ErrorKind}; /// let res = App::new("prog") @@ -1607,14 +1608,6 @@ impl<'help> Arg<'help> { /// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid /// if one of the specified `arg`'s value equals its corresponding `val`. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// required_if_eq: - /// - [arg, val] - /// - [arg2, val2] - /// ``` - /// /// # Examples /// /// ```rust @@ -1627,6 +1620,14 @@ impl<'help> Arg<'help> { /// # ; /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// required_if_eq: + /// - [arg, val] + /// - [arg2, val2] + /// ``` + /// /// Setting `Arg::required_if_eq_any(&[(arg, val)])` makes this arg required if any of the `arg`s /// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is /// anything other than `val`, this argument isn't required. @@ -1699,14 +1700,6 @@ impl<'help> Arg<'help> { /// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid /// if every one of the specified `arg`'s value equals its corresponding `val`. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// required_if_eq_all: - /// - [arg, val] - /// - [arg2, val2] - /// ``` - /// /// # Examples /// /// ```rust @@ -1719,6 +1712,14 @@ impl<'help> Arg<'help> { /// # ; /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// required_if_eq_all: + /// - [arg, val] + /// - [arg2, val2] + /// ``` + /// /// Setting `Arg::required_if_eq_all(&[(arg, val)])` makes this arg required if all of the `arg`s /// are used at runtime and every value is equal to its corresponding `val`. If the `arg`'s value is /// anything other than `val`, this argument isn't required. @@ -2356,12 +2357,6 @@ impl<'help> Arg<'help> { /// The regular expression can either be borrowed or moved into `validator_regex`. This happens /// automatically via [`RegexRef`]'s `Into` implementation. /// - /// **NOTE:** If using YAML then a single vector with two entries should be provided: - /// - /// ```yaml - /// validator_regex: [remove-all-files, needs the exact phrase 'remove-all-files' to continue] - /// ``` - /// /// # Performance /// Regular expressions are expensive to compile. You should prefer sharing your regular expression. /// We use a [`Cow`]-like internal structure to enable both sharing as well as taking ownership of a @@ -2406,6 +2401,11 @@ impl<'help> Arg<'help> { /// assert!(res.is_err()); /// assert_eq!(res.err().unwrap().kind, ErrorKind::ValueValidation) /// ``` + /// + /// If using YAML then a single vector with two entries should be provided: + /// ```yaml + /// validator_regex: [remove-all-files, needs the exact phrase 'remove-all-files' to continue] + /// ``` #[cfg(feature = "regex")] pub fn validator_regex( self, @@ -2955,14 +2955,6 @@ impl<'help> Arg<'help> { /// /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`]. /// - /// **NOTE:** If using YAML the values should be laid out as follows (`None` can be represented - /// as `null` in YAML) - /// - /// ```yaml - /// default_value_if: - /// - [arg, val, default] - /// ``` - /// /// # Examples /// /// First we use the default value only if another arg is present at runtime. @@ -2982,6 +2974,14 @@ impl<'help> Arg<'help> { /// assert_eq!(m.value_of("other"), Some("default")); /// ``` /// + /// If using YAML the values should be laid out as follows (`None` can be represented + /// as `null` in YAML) + /// + /// ```yaml + /// default_value_if: + /// - [arg, val, default] + /// ``` + /// /// Next we run the same test, but without providing `--flag`. /// /// ```rust @@ -3086,14 +3086,6 @@ impl<'help> Arg<'help> { /// **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. /// - /// **NOTE:** If using YAML the values should be laid out as follows - /// - /// ```yaml - /// default_value_if: - /// - [arg, val, default] - /// - [arg2, null, default2] - /// ``` - /// /// # Examples /// /// First we use the default value only if another arg is present at runtime. @@ -3119,6 +3111,14 @@ impl<'help> Arg<'help> { /// assert_eq!(m.value_of("other"), Some("chan")); /// ``` /// + /// If using YAML the values should be laid out as follows + /// + /// ```yaml + /// default_value_if: + /// - [arg, val, default] + /// - [arg2, null, default2] + /// ``` + /// /// Next we run the same test, but without providing `--flag`. /// /// ```rust From 45ef0722f3bc14031877bd90ee9748d8111bab13 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Sat, 16 Oct 2021 13:42:33 -0500 Subject: [PATCH 2/2] docs: Clarify corner caseses with default values This is meant to lower the chance of confusion with cases like #2714 and #1586. This is not meant to be exhaustive, looked at the mentioned cases in that issue and pattern matched on other ones mentioning "is present". --- src/build/arg/mod.rs | 12 ++++++++++++ src/build/arg_group.rs | 10 ++++++++++ 2 files changed, 22 insertions(+) diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index af1d0e18..6495c619 100644 --- a/src/build/arg/mod.rs +++ b/src/build/arg/mod.rs @@ -1045,6 +1045,8 @@ impl<'help> Arg<'help> { /// /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -1095,6 +1097,8 @@ impl<'help> Arg<'help> { /// /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -1328,6 +1332,8 @@ impl<'help> Arg<'help> { /// /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// + /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -1389,6 +1395,8 @@ impl<'help> Arg<'help> { /// if this arg (`self`) is present and its value equals to `val`. /// If it does, `another_arg` will be marked as required. /// + /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -1510,6 +1518,8 @@ impl<'help> Arg<'help> { /// Allows specifying that this argument is [required] only if the specified /// `arg` is present at runtime and its value equals `val`. /// + /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -1786,6 +1796,8 @@ impl<'help> Arg<'help> { /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required /// by default. /// + /// **NOTE:** This argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust diff --git a/src/build/arg_group.rs b/src/build/arg_group.rs index 809441c5..83d4ad11 100644 --- a/src/build/arg_group.rs +++ b/src/build/arg_group.rs @@ -249,6 +249,8 @@ impl<'help> ArgGroup<'help> { /// 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." /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -284,6 +286,8 @@ impl<'help> ArgGroup<'help> { /// /// **NOTE:** The name provided may be an argument, or group name /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -319,6 +323,8 @@ impl<'help> ArgGroup<'help> { /// /// **NOTE:** The names provided may be an argument, or group name /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -357,6 +363,8 @@ impl<'help> ArgGroup<'help> { /// /// **NOTE:** The name provided may be an argument, or group name /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust @@ -389,6 +397,8 @@ impl<'help> ArgGroup<'help> { /// /// **NOTE:** The names provided may be an argument, or group name /// + /// **NOTE:** An argument is considered present when there is a [`Arg::default_value`] + /// /// # Examples /// /// ```rust