Merge pull request clap-rs#3700 from epage/value_name

fix(help): Define value name / number of values mismatch relationships

src/build/arg.rs

@@ -5287,7 +5287,10 @@ where
                         write(&delim, false)?;
                     }
                 }
-                if (num_val_names == 1 && mult_val) || (arg.is_positional() && mult_occ) {
+                if (num_val_names == 1 && mult_val)
+                    || (arg.is_positional() && mult_occ)
+                    || num_val_names < arg.num_vals.unwrap_or(0)
+                {
                     write("...", true)?;
                 }
             }

src/build/debug_asserts.rs

@@ -636,6 +636,18 @@ fn assert_arg(arg: &Arg) {
         );
     }
 
+    #[cfg(feature = "unstable-v4")]
+    {
+        let num_vals = arg.get_num_vals().unwrap_or(usize::MAX);
+        let num_val_names = arg.get_value_names().unwrap_or(&[]).len();
+        if num_vals < num_val_names {
+            panic!(
+                "Argument {}: Too many value names ({}) compared to number_of_values ({})",
+                arg.name, num_val_names, num_vals
+            );
+        }
+    }
+
     assert_arg_flags(arg);
 
     assert_defaults(arg, "default_value", arg.default_vals.iter().copied());

tests/builder/help.rs

@@ -2552,6 +2552,63 @@ OPTIONS:
     );
 }
 
+#[test]
+fn too_few_value_names_is_dotted() {
+    let cmd = Command::new("test").arg(
+        Arg::new("foo")
+            .long("foo")
+            .required(true)
+            .takes_value(true)
+            .number_of_values(3)
+            .value_names(&["one", "two"]),
+    );
+    utils::assert_output(
+        cmd,
+        "test --help",
+        "test 
+
+USAGE:
+    test --foo <one> <two>...
+
+OPTIONS:
+        --foo <one> <two>...    
+    -h, --help                  Print help information
+",
+        false,
+    );
+}
+
+#[test]
+#[cfg(not(feature = "unstable-v4"))]
+fn too_many_value_names_panics() {
+    Command::new("test")
+        .arg(
+            Arg::new("foo")
+                .long("foo")
+                .required(true)
+                .takes_value(true)
+                .number_of_values(1)
+                .value_names(&["one", "two"]),
+        )
+        .debug_assert()
+}
+
+#[test]
+#[cfg(feature = "unstable-v4")]
+#[should_panic = "Argument foo: Too many value names (2) compared to number_of_values (1)"]
+fn too_many_value_names_panics() {
+    Command::new("test")
+        .arg(
+            Arg::new("foo")
+                .long("foo")
+                .required(true)
+                .takes_value(true)
+                .number_of_values(1)
+                .value_names(&["one", "two"]),
+        )
+        .debug_assert()
+}
+
 #[test]
 fn disabled_help_flag() {
     let res = Command::new("foo")