feat: Prefix argument long aliases in help output with --

Cargo.toml

@@ -16,6 +16,6 @@ categories = ["command-line-interface", "command-line-utilities", "development-t
 clap = "4.*.*"
 
 [dev-dependencies]
-clap = { version = "4.4.0", features = ["derive"] }
+clap = { version = "4.5.38", features = ["derive"] }
 
 pretty_assertions = "1.3.0"

docs/examples/complex-app-custom.md

@@ -21,7 +21,7 @@ An example command-line tool
 
 ###### **Options:**
 
-* `-c`, `--config <FILE>` [alias: `configuration`] — Sets a custom config file
+* `-c`, `--config <FILE>` [alias: `--configuration`] — Sets a custom config file
 * `--target <TARGET>`
 
   Default value: `local`
@@ -31,7 +31,7 @@ An example command-line tool
     Do the operation locally
   - `remote`
 
-* `--very-very-verbose` [aliases: `vv`, `vvv`]
+* `--very-very-verbose` [aliases: `--vv`, `--vvv`]
 * `-d`, `--debug` — Turn debugging information on
 
    Repeat this option to see more and more debug information.

docs/examples/complex-app.md

@@ -27,7 +27,7 @@ An example command-line tool
 
 ###### **Options:**
 
-* `-c`, `--config <FILE>` [alias: `configuration`] — Sets a custom config file
+* `-c`, `--config <FILE>` [alias: `--configuration`] — Sets a custom config file
 * `--target <TARGET>`
 
   Default value: `local`
@@ -37,7 +37,7 @@ An example command-line tool
     Do the operation locally
   - `remote`
 
-* `--very-very-verbose` [aliases: `vv`, `vvv`]
+* `--very-very-verbose` [aliases: `--vv`, `--vvv`]
 * `-d`, `--debug` — Turn debugging information on
 
    Repeat this option to see more and more debug information.

src/lib.rs

@@ -354,7 +354,9 @@ fn build_command_markdown(
 
     if options.show_aliases {
         let aliases = command.get_visible_aliases().collect::<Vec<&str>>();
-        if let Some(aliases_str) = get_alias_string(&aliases) {
+        if let Some(aliases_str) =
+            get_alias_string(&aliases, &AliasFor::Command)
+        {
             writeln!(
                 buffer,
                 "**{}:** {aliases_str}\n",
@@ -491,7 +493,7 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
     }
 
     if let Some(aliases) = arg.get_visible_aliases().as_deref() {
-        if let Some(aliases_str) = get_alias_string(aliases) {
+        if let Some(aliases_str) = get_alias_string(aliases, &AliasFor::Arg) {
             write!(
                 buffer,
                 " [{}: {aliases_str}]",
@@ -626,28 +628,32 @@ fn indent(s: &str, first: &str, rest: &str) -> String {
     result
 }
 
-fn get_alias_string(aliases: &[&str]) -> Option<String> {
+enum AliasFor {
+    Command,
+    Arg,
+}
+
+fn get_alias_string(aliases: &[&str], alias_for: &AliasFor) -> Option<String> {
     if aliases.is_empty() {
         return None;
     }
-
-    Some(format!(
-        "{}",
-        aliases
-            .iter()
-            .map(|alias| format!("`{alias}`"))
-            .collect::<Vec<_>>()
-            .join(", ")
-    ))
+    let aliases: Vec<_> = aliases
+        .iter()
+        .map(|alias| match alias_for {
+            AliasFor::Command => format!("`{alias}`"),
+            AliasFor::Arg => format!("`--{alias}`"),
+        })
+        .collect();
+    Some(aliases.join(", "))
 }
 
 #[cfg(test)]
 mod test {
+    use super::*;
     use pretty_assertions::assert_eq;
 
     #[test]
     fn test_indent() {
-        use super::indent;
         assert_eq!(
             &indent("Header\n\nMore info", "___", "~~~~"),
             "___Header\n\n~~~~More info\n"
@@ -659,4 +665,40 @@ mod test {
         assert_eq!(&indent("", "___", "~~~~"), "\n");
         assert_eq!(&indent("\n", "___", "~~~~"), "\n");
     }
+
+    #[test]
+    fn test_get_alias_string_for_command() {
+        let aliases = &[];
+        assert!(get_alias_string(aliases, &AliasFor::Command).is_none());
+
+        let aliases = &["foo"];
+        assert_eq!(
+            get_alias_string(aliases, &AliasFor::Command).unwrap(),
+            "`foo`"
+        );
+
+        let aliases = &["foo", "bar", "baz"];
+        assert_eq!(
+            get_alias_string(aliases, &AliasFor::Command).unwrap(),
+            "`foo`, `bar`, `baz`"
+        );
+    }
+
+    #[test]
+    fn test_get_alias_string_for_arg() {
+        let aliases = &[];
+        assert!(get_alias_string(aliases, &AliasFor::Arg).is_none());
+
+        let aliases = &["foo"];
+        assert_eq!(
+            get_alias_string(aliases, &AliasFor::Arg).unwrap(),
+            "`--foo`"
+        );
+
+        let aliases = &["foo", "bar", "baz"];
+        assert_eq!(
+            get_alias_string(aliases, &AliasFor::Arg).unwrap(),
+            "`--foo`, `--bar`, `--baz`"
+        );
+    }
 }