feature: Include Arg value name and default values in generated Markd…

…own (ConnorGray#11)

* polish: Use `value` instead of **value** for Arg possible values

* feature: Include Arg value name in generated Markdown

This makes the intended usage of the option clearer.

It also distinguishes between "options" (which take values), and
"flags" (which don't take values).

* polish: Use "Possible values:" for both possible values display forms (with and without help)

* feature: Include Arg default values in generated Markdown

docs/examples/complex-app.md

@@ -23,13 +23,15 @@ An example command-line tool
 
 ###### **Options:**
 
-* `-c`, `--config` — Sets a custom config file
-* `--target`
+* `-c`, `--config <FILE>` — Sets a custom config file
+* `--target <TARGET>`
+
+  Default value: `local`
 
   Possible values:
-  - **local**:
+  - `local`:
     Do the operation locally
-  - **remote**
+  - `remote`
 
 * `-d`, `--debug` — Turn debugging information on
 

docs/examples/complex_app.rs

@@ -13,8 +13,8 @@ pub struct Cli {
     #[arg(short, long, value_name = "FILE")]
     config: Option<PathBuf>,
 
-    #[arg(long)]
-    target: Option<Target>,
+    #[arg(long, default_value = "local")]
+    target: Target,
 
     /// Turn debugging information on
     #[arg(short, long, action = clap::ArgAction::Count)]

src/lib.rs

@@ -341,20 +341,41 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
     // Markdown list item
     write!(buffer, "* ")?;
 
+    let value_name: String = match arg.get_value_names() {
+        // TODO: What if multiple names are provided?
+        Some([name, ..]) => name.as_str().to_owned(),
+        Some([]) => unreachable!(
+            "clap Arg::get_value_names() returned Some(..) of empty list"
+        ),
+        None => arg.get_id().to_string().to_ascii_uppercase(),
+    };
+
     match (arg.get_short(), arg.get_long()) {
         (Some(short), Some(long)) => {
-            write!(buffer, "`-{}`, `--{}`", short, long)?
+            if arg.get_action().takes_values() {
+                write!(buffer, "`-{short}`, `--{long} <{value_name}>`")?
+            } else {
+                write!(buffer, "`-{short}`, `--{long}`")?
+            }
+        },
+        (Some(short), None) => {
+            if arg.get_action().takes_values() {
+                write!(buffer, "`-{short} <{value_name}>`")?
+            } else {
+                write!(buffer, "`-{short}`")?
+            }
+        },
+        (None, Some(long)) => {
+            if arg.get_action().takes_values() {
+                write!(buffer, "`--{} <{value_name}>`", long)?
+            } else {
+                write!(buffer, "`--{}`", long)?
+            }
         },
-        (Some(short), None) => write!(buffer, "`-{}`", short)?,
-        (None, Some(long)) => write!(buffer, "`--{}`", long)?,
         (None, None) => {
             debug_assert!(arg.is_positional(), "unexpected non-positional Arg with neither short nor long name: {arg:?}");
 
-            write!(
-                buffer,
-                "`<{}>`",
-                arg.get_id().to_string().to_ascii_uppercase()
-            )?;
+            write!(buffer, "`<{value_name}>`",)?;
         },
     }
 
@@ -364,6 +385,27 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
         writeln!(buffer)?;
     }
 
+    //--------------------
+    // Arg default values
+    //--------------------
+
+    if !arg.get_default_values().is_empty() {
+        let default_values: String = arg
+            .get_default_values()
+            .iter()
+            .map(|value| format!("`{}`", value.to_string_lossy()))
+            .collect::<Vec<String>>()
+            .join(", ");
+
+        if arg.get_default_values().len() > 1 {
+            // Plural
+            writeln!(buffer, "\n  Default values: {default_values}")?;
+        } else {
+            // Singular
+            writeln!(buffer, "\n  Default value: {default_values}")?;
+        }
+    }
+
     //--------------------
     // Arg possible values
     //--------------------
@@ -384,19 +426,19 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
             // help text for those that have it. E.g.:
             //
             //     Possible values:
-            //     - **value1**:
+            //     - `value1`:
             //       The help text
-            //     - **value2**
-            //     - **value3**:
+            //     - `value2`
+            //     - `value3`:
             //       The help text
 
             let text: String = possible_values
                 .iter()
                 .map(|pv| match pv.get_help() {
                     Some(help) => {
-                        format!("  - **{}**:\n    {}\n", pv.get_name(), help)
+                        format!("  - `{}`:\n    {}\n", pv.get_name(), help)
                     },
-                    None => format!("  - **{}**\n", pv.get_name()),
+                    None => format!("  - `{}`\n", pv.get_name()),
                 })
                 .collect::<Vec<String>>()
                 .join("");
@@ -412,7 +454,7 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
                 .collect::<Vec<String>>()
                 .join(", ");
 
-            writeln!(buffer, "\n  *Possible Values:* {text}\n")?;
+            writeln!(buffer, "\n  Possible values: {text}\n")?;
         }
     }