Improve SubcommandPrecedenceOverArg description

Signed-off-by: David McNeil <mcneil.david2@gmail.com>

src/build/app/settings.rs

@@ -442,13 +442,57 @@ pub enum AppSettings {
     /// Instructs the parser to stop when encountering a subcommand instead of greedily consuming
     /// args.
     ///
+    /// By default, if an option taking multiple values is followed by a subcommand, the
+    /// subcommand will be parsed as another value.
+    ///
+    /// ```text
+    /// app --foo val1 val2 subcommand
+    ///           --------- ----------
+    ///             values   another value
+    /// ```
+    ///
+    /// This setting instructs the parser to stop when encountering a subcommand instead of
+    /// greedily consuming arguments.
+    ///
+    /// ```text
+    /// app --foo val1 val2 subcommand
+    ///           --------- ----------
+    ///             values   subcommand
+    /// ```
+    ///
+    /// **Note:** Make sure you apply it as `global_setting` if you want it to be propagated to
+    /// sub-sub commands!
+    ///
     /// # Examples
     ///
     /// ```rust
-    /// # use clap::{App, AppSettings};
-    /// App::new("myprog")
-    ///     .setting(AppSettings::SubcommandPrecedenceOverArg)
-    /// # ;
+    /// # use clap::{App, AppSettings, Arg};
+    /// let app = App::new("app").subcommand(App::new("sub")).arg(
+    /// Arg::with_name("arg")
+    ///     .long("arg")
+    ///     .multiple(true)
+    ///     .takes_value(true),
+    /// );
+    ///
+    /// let matches = app
+    ///     .clone()
+    ///     .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
+    ///     .unwrap();
+    /// assert_eq!(
+    ///     matches.values_of("arg").unwrap().collect::<Vec<_>>(),
+    ///     &["1", "2", "3", "sub"]
+    /// );
+    /// assert!(matches.subcommand_matches("sub").is_none());
+    ///
+    /// let app = app.setting(AppSettings::SubcommandPrecedenceOverArg);
+    /// let matches = app
+    ///     .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
+    ///     .unwrap();
+    /// assert_eq!(
+    ///     matches.values_of("arg").unwrap().collect::<Vec<_>>(),
+    ///     &["1", "2", "3"]
+    /// );
+    /// assert!(matches.subcommand_matches("sub").is_some());
     /// ```
     SubcommandPrecedenceOverArg,
 

tests/app_settings.rs

@@ -124,36 +124,6 @@ fn arg_required_else_help_over_reqs() {
     assert_eq!(err.kind, ErrorKind::MissingArgumentOrSubcommand);
 }
 
-#[test]
-fn subcommand_precedence_over_arg() {
-    let app = App::new("app").subcommand(App::new("sub")).arg(
-        Arg::with_name("arg")
-            .long("arg")
-            .multiple(true)
-            .takes_value(true),
-    );
-
-    let matches = app
-        .clone()
-        .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
-        .unwrap();
-    assert_eq!(
-        matches.values_of("arg").unwrap().collect::<Vec<_>>(),
-        &["1", "2", "3", "sub"]
-    );
-    assert!(matches.subcommand_matches("sub").is_none());
-
-    let app = app.setting(AppSettings::SubcommandPrecedenceOverArg);
-    let matches = app
-        .try_get_matches_from(&["app", "--arg", "1", "2", "3", "sub"])
-        .unwrap();
-    assert_eq!(
-        matches.values_of("arg").unwrap().collect::<Vec<_>>(),
-        &["1", "2", "3"]
-    );
-    assert!(matches.subcommand_matches("sub").is_some());
-}
-
 #[cfg(not(feature = "suggestions"))]
 #[test]
 fn infer_subcommands_fail_no_args() {

tests/subcommands.rs

@@ -1,6 +1,6 @@
 mod utils;
 
-use clap::{App, AppSettings, Arg, ErrorKind};
+use clap::{App, Arg, ErrorKind};
 
 static VISIBLE_ALIAS_HELP: &str = "clap-test 2.6