[Draft] About for Possible Value

clap_generate/src/generators/shells/bash.rs

@@ -185,7 +185,10 @@ fn vals_for(o: &Arg) -> String {
     debug!("vals_for: o={}", o.get_name());
 
     if let Some(vals) = o.get_possible_values() {
-        format!("$(compgen -W \"{}\" -- \"${{cur}}\")", vals.join(" "))
+        format!(
+            "$(compgen -W \"{}\" -- \"${{cur}}\")",
+            vals.iter().map(|&(pv, _)| pv).collect::<Vec<_>>().join(" ")
+        )
     } else {
         String::from("$(compgen -f \"${cur}\")")
     }

clap_generate/src/generators/shells/fish.rs

@@ -133,7 +133,13 @@ fn value_completion(option: &Arg) -> String {
     }
 
     if let Some(data) = option.get_possible_values() {
-        format!(" -r -f -a \"{}\"", data.join(" "))
+        format!(
+            " -r -f -a \"{{{}}}\"",
+            data.iter()
+                .map(|&(name, about)| format!("{}\t{}", name, about.unwrap_or_default()))
+                .collect::<Vec<_>>()
+                .join(",")
+        )
     } else {
         // NB! If you change this, please also update the table in `ValueHint` documentation.
         match option.get_value_hint() {

clap_generate/src/generators/shells/zsh.rs

@@ -344,14 +344,31 @@ fn get_args_of(parent: &App, p_global: Option<&App>) -> String {
 // Uses either `possible_vals` or `value_hint` to give hints about possible argument values
 fn value_completion(arg: &Arg) -> Option<String> {
     if let Some(values) = &arg.get_possible_values() {
-        Some(format!(
-            "({})",
-            values
-                .iter()
-                .map(|&v| escape_value(v))
-                .collect::<Vec<_>>()
-                .join(" ")
-        ))
+        if values.iter().any(|(_, about)| about.is_some()) {
+            Some(format!(
+                "(({}))",
+                values
+                    .iter()
+                    .map(|&(name, about)| {
+                        format!(
+                            r#"{name}\:"{about}""#,
+                            name = escape_value(name),
+                            about = about.map(|about| escape_help(about)).unwrap_or_default()
+                        )
+                    })
+                    .collect::<Vec<_>>()
+                    .join("\n")
+            ))
+        } else {
+            Some(format!(
+                "({})",
+                values
+                    .iter()
+                    .map(|&(name, _)| name)
+                    .collect::<Vec<_>>()
+                    .join(" ")
+            ))
+        }
     } else {
         // NB! If you change this, please also update the table in `ValueHint` documentation.
         Some(

clap_generate/tests/value_hints.rs

@@ -131,7 +131,7 @@ _my_app_commands() {
 
 _my_app "$@""#;
 
-static FISH_VALUE_HINTS: &str = r#"complete -c my_app -l choice -r -f -a "bash fish zsh"
+static FISH_VALUE_HINTS: &str = r#"complete -c my_app -l choice -r -f -a "{bash	,fish	,zsh	}"
 complete -c my_app -l unknown -r
 complete -c my_app -l other -r -f
 complete -c my_app -s p -l path -r -F

src/build/arg/mod.rs

@@ -101,7 +101,7 @@ pub struct Arg<'help> {
     pub(crate) short_aliases: Vec<(char, bool)>, // (name, visible)
     pub(crate) disp_ord: usize,
     pub(crate) unified_ord: usize,
-    pub(crate) possible_vals: Vec<&'help str>,
+    pub(crate) possible_vals: Vec<(&'help str, Option<&'help str>)>,
     pub(crate) val_names: Vec<&'help str>,
     pub(crate) num_vals: Option<usize>,
     pub(crate) max_occurs: Option<usize>,
@@ -230,7 +230,7 @@ impl<'help> Arg<'help> {
 
     /// Get the list of the possible values for this argument, if any
     #[inline]
-    pub fn get_possible_values(&self) -> Option<&[&str]> {
+    pub fn get_possible_values(&self) -> Option<&[(&str, Option<&str>)]> {
         if self.possible_vals.is_empty() {
             None
         } else {
@@ -1904,7 +1904,19 @@ impl<'help> Arg<'help> {
     /// [options]: Arg::takes_value()
     /// [positional arguments]: Arg::index()
     pub fn possible_values(mut self, names: &[&'help str]) -> Self {
-        self.possible_vals.extend(names);
+        self.possible_vals
+            .extend(names.iter().map(|&name| (name, None)).collect::<Vec<_>>());
+        self.takes_value(true)
+    }
+
+    /// TODO Docu
+    pub fn possible_values_about(mut self, values: &[(&'help str, &'help str)]) -> Self {
+        self.possible_vals.extend(
+            values
+                .iter()
+                .map(|&(name, about)| (name, (!about.is_empty()).then(|| about)))
+                .collect::<Vec<_>>(),
+        );
         self.takes_value(true)
     }
 
@@ -1962,7 +1974,13 @@ impl<'help> Arg<'help> {
     /// [options]: Arg::takes_value()
     /// [positional arguments]: Arg::index()
     pub fn possible_value(mut self, name: &'help str) -> Self {
-        self.possible_vals.push(name);
+        self.possible_vals.push((name, None));
+        self.takes_value(true)
+    }
+
+    /// TODO Docu
+    pub fn possible_value_about(mut self, name: &'help str, about: &'help str) -> Self {
+        self.possible_vals.push((name, Some(about)));
         self.takes_value(true)
     }
 

src/output/help.rs

@@ -596,7 +596,7 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
             let pvs = a
                 .possible_vals
                 .iter()
-                .map(|&pv| {
+                .map(|&(pv, _)| {
                     if pv.contains(char::is_whitespace) {
                         format!("{:?}", pv)
                     } else {

src/parse/validator.rs

@@ -107,9 +107,9 @@ impl<'help, 'app, 'parser> Validator<'help, 'app, 'parser> {
                 let ok = if arg.is_set(ArgSettings::IgnoreCase) {
                     arg.possible_vals
                         .iter()
-                        .any(|pv| pv.eq_ignore_ascii_case(&val_str))
+                        .any(|(pv, _)| pv.eq_ignore_ascii_case(&val_str))
                 } else {
-                    arg.possible_vals.contains(&&*val_str)
+                    arg.possible_vals.iter().any(|(pv, _)| pv == &&*val_str)
                 };
                 if !ok {
                     let used: Vec<Id> = matcher
@@ -123,7 +123,10 @@ impl<'help, 'app, 'parser> Validator<'help, 'app, 'parser> {
                         .collect();
                     return Err(Error::invalid_value(
                         val_str.to_string(),
-                        &arg.possible_vals,
+                        &arg.possible_vals
+                            .iter()
+                            .map(|(pv, _)| pv)
+                            .collect::<Vec<_>>(),
                         arg,
                         Usage::new(self.p).create_usage_with_title(&used),
                         self.p.app.color(),