Merge pull request #3837 from epage/bool

docs: Provide a hybrid-flag example

src/builder/action.rs

@@ -92,7 +92,8 @@ pub enum ArgAction {
     ///
     /// If no [`default_value`][super::Arg::default_value] is set, it will be `false`.
     ///
-    /// No value is allowed
+    /// No value is allowed. To optionally accept a value, see
+    /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
     ///
     /// # Examples
     ///
@@ -127,7 +128,8 @@ pub enum ArgAction {
     ///
     /// If no [`default_value`][super::Arg::default_value] is set, it will be `true`.
     ///
-    /// No value is allowed
+    /// No value is allowed. To optionally accept a value, see
+    /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
     ///
     /// # Examples
     ///
@@ -162,7 +164,8 @@ pub enum ArgAction {
     ///
     /// If no [`default_value`][super::Arg::default_value] is set, it will be `0`.
     ///
-    /// No value is allowed
+    /// No value is allowed. To optionally accept a value, see
+    /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
     ///
     /// # Examples
     ///

src/builder/arg.rs

@@ -2220,59 +2220,79 @@ impl<'help> Arg<'help> {
     ///
     /// # Examples
     ///
-    /// Here is an implementation of the common POSIX style `--color` argument.
-    ///
+    /// For POSIX style `--color`:
     /// ```rust
     /// # use clap::{Command, Arg, ValueSource};
-    ///
-    /// macro_rules! cmd {
-    ///     () => {{
-    ///         Command::new("prog")
-    ///             .arg(Arg::new("color").long("color")
-    ///                 .value_name("WHEN")
-    ///                 .value_parser(["always", "auto", "never"])
-    ///                 .default_value("auto")
-    ///                 .overrides_with("color")
-    ///                 .min_values(0)
-    ///                 .require_equals(true)
-    ///                 .default_missing_value("always")
-    ///                 .help("Specify WHEN to colorize output.")
-    ///             )
-    ///    }};
+    /// fn cli() -> Command<'static> {
+    ///     Command::new("prog")
+    ///         .arg(Arg::new("color").long("color")
+    ///             .value_name("WHEN")
+    ///             .value_parser(["always", "auto", "never"])
+    ///             .default_value("auto")
+    ///             .min_values(0)
+    ///             .require_equals(true)
+    ///             .default_missing_value("always")
+    ///             .help("Specify WHEN to colorize output.")
+    ///         )
     /// }
     ///
-    /// let mut m;
-    ///
     /// // first, we'll provide no arguments
-    ///
-    /// m  = cmd!().get_matches_from(vec![
+    /// let m  = cli().get_matches_from(vec![
     ///         "prog"
     ///     ]);
-    ///
     /// assert_eq!(m.value_of("color"), Some("auto"));
-    /// assert!(m.contains_id("color"));
     /// assert_eq!(m.value_source("color"), Some(ValueSource::DefaultValue));
     ///
     /// // next, we'll provide a runtime value to override the default (as usually done).
-    ///
-    /// m  = cmd!().get_matches_from(vec![
+    /// let m  = cli().get_matches_from(vec![
     ///         "prog", "--color=never"
     ///     ]);
-    ///
     /// assert_eq!(m.value_of("color"), Some("never"));
-    /// assert!(m.contains_id("color"));
     /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
     ///
     /// // finally, we will use the shortcut and only provide the argument without a value.
-    ///
-    /// m  = cmd!().get_matches_from(vec![
+    /// let m  = cli().get_matches_from(vec![
     ///         "prog", "--color"
     ///     ]);
-    ///
     /// assert_eq!(m.value_of("color"), Some("always"));
-    /// assert!(m.contains_id("color"));
     /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
     /// ```
+    ///
+    /// For bool literals:
+    /// ```rust
+    /// # use clap::{Command, Arg, ValueSource, value_parser};
+    /// fn cli() -> Command<'static> {
+    ///     Command::new("prog")
+    ///         .arg(Arg::new("create").long("create")
+    ///             .value_name("BOOL")
+    ///             .value_parser(value_parser!(bool))
+    ///             .min_values(0)
+    ///             .require_equals(true)
+    ///             .default_missing_value("true")
+    ///         )
+    /// }
+    ///
+    /// // first, we'll provide no arguments
+    /// let m  = cli().get_matches_from(vec![
+    ///         "prog"
+    ///     ]);
+    /// assert_eq!(m.get_one::<bool>("create").copied(), None);
+    ///
+    /// // next, we'll provide a runtime value to override the default (as usually done).
+    /// let m  = cli().get_matches_from(vec![
+    ///         "prog", "--create=false"
+    ///     ]);
+    /// assert_eq!(m.get_one::<bool>("create").copied(), Some(false));
+    /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
+    ///
+    /// // finally, we will use the shortcut and only provide the argument without a value.
+    /// let m  = cli().get_matches_from(vec![
+    ///         "prog", "--create"
+    ///     ]);
+    /// assert_eq!(m.get_one::<bool>("create").copied(), Some(true));
+    /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
+    /// ```
+    ///
     /// [`ArgMatches::value_of`]: ArgMatches::value_of()
     /// [`Arg::takes_value(true)`]: Arg::takes_value()
     /// [`Arg::default_value`]: Arg::default_value()