doc(parser): Document external subcommand escaping behavior

src/build/command.rs

@@ -2709,11 +2709,16 @@ impl<'help> App<'help> {
 
     /// Assume unexpected positional arguments are a [`subcommand`].
     ///
+    /// 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

tests/builder/app_settings.rs

@@ -930,6 +930,25 @@ fn external_subcommand_looks_like_built_in() {
     }
 }
 
+#[test]
+fn built_in_subcommand_escaped() {
+    let res = Command::new("cargo")
+        .version("1.26.0")
+        .allow_external_subcommands(true)
+        .allow_invalid_utf8_for_external_subcommands(true)
+        .subcommand(Command::new("install"))
+        .try_get_matches_from(vec!["cargo", "--", "install", "foo"]);
+    assert!(res.is_ok(), "{}", res.unwrap_err());
+    let m = res.unwrap();
+    match m.subcommand() {
+        Some((name, args)) => {
+            assert_eq!(name, "install");
+            assert_eq!(args.values_of_lossy(""), Some(vec!["foo".to_string()]));
+        }
+        _ => panic!("external_subcommand didn't work"),
+    }
+}
+
 #[test]
 fn aaos_flags() {
     // flags