From ab3623f65a9ada6c60f47e9061d793bcf1857e6f Mon Sep 17 00:00:00 2001
From: Terts Diepraam <terts.diepraam@gmail.com>
Date: Fri, 21 Jan 2022 19:20:55 +0100
Subject: [PATCH] docs: usage and values for options

---
 src/bin/uudoc.rs                | 46 ++++++++++++++++++++++++++++-----
 src/uu/sum/src/sum.rs           |  6 ++---
 src/uu/unexpand/src/unexpand.rs |  4 +--
 3 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/src/bin/uudoc.rs b/src/bin/uudoc.rs
index 6155fa8b2..1b0376189 100644
--- a/src/bin/uudoc.rs
+++ b/src/bin/uudoc.rs
@@ -19,7 +19,7 @@ fn main() {
     for (name, (_, app)) in utils {
         let p = format!("docs/_generated/{}-help.md", name);
         if let Ok(f) = File::create(&p) {
-            write_markdown(f, &mut app());
+            write_markdown(f, &mut app(), name);
             println!("Wrote to '{}'", p);
         } else {
             println!("Error writing to {}", p);
@@ -27,8 +27,9 @@ fn main() {
     }
 }
 
-fn write_markdown(mut w: impl Write, app: &mut App) {
+fn write_markdown(mut w: impl Write, app: &mut App, name: &str) {
     write_version(&mut w, app);
+    write_usage(&mut w, app, name);
     write_summary(&mut w, app);
     write_options(&mut w, app);
 }
@@ -41,6 +42,14 @@ fn write_version(w: &mut impl Write, app: &App) {
     );
 }
 
+fn write_usage(w: &mut impl Write, app: &mut App, name: &str) {
+    let _ = writeln!(w, "\n```");
+    let mut usage: String = app.render_usage().lines().nth(1).unwrap().trim().into();
+    usage = usage.replace(app.get_name(), name);
+    let _ = writeln!(w, "{}", usage);
+    let _ = writeln!(w, "```");
+}
+
 fn write_summary(w: &mut impl Write, app: &App) {
     if let Some(about) = app.get_long_about().or_else(|| app.get_about()) {
         let _ = writeln!(w, "{}", about);
@@ -59,18 +68,43 @@ fn write_options(w: &mut impl Write, app: &App) {
             } else {
                 first = false;
             }
-            let _ = write!(w, "<code>--{}</code>", l);
+            let _ = write!(w, "<code>");
+            let _ = write!(w, "--{}", l);
+            if let Some(names) = arg.get_value_names() {
+                let _ = write!(
+                    w,
+                    "={}",
+                    names
+                        .iter()
+                        .map(|x| format!("&lt;{}&gt;", x))
+                        .collect::<Vec<_>>()
+                        .join(" ")
+                );
+            }
+            let _ = write!(w, "</code>");
         }
-        for l in arg.get_short_and_visible_aliases().unwrap_or_default() {
+        for s in arg.get_short_and_visible_aliases().unwrap_or_default() {
             if !first {
                 let _ = write!(w, ", ");
             } else {
                 first = false;
             }
-            let _ = write!(w, "<code>-{}</code>", l);
+            let _ = write!(w, "<code>");
+            let _ = write!(w, "-{}", s);
+            if let Some(names) = arg.get_value_names() {
+                let _ = write!(
+                    w,
+                    " {}",
+                    names
+                        .iter()
+                        .map(|x| format!("&lt;{}&gt;", x))
+                        .collect::<Vec<_>>()
+                        .join(" ")
+                );
+            }
+            let _ = write!(w, "</code>");
         }
         let _ = writeln!(w, "</dt>");
-
         let _ = writeln!(w, "<dd>{}</dd>", arg.get_help().unwrap_or_default());
     }
     let _ = writeln!(w, "</dl>");
diff --git a/src/uu/sum/src/sum.rs b/src/uu/sum/src/sum.rs
index 67bff31b0..1c2b19ba5 100644
--- a/src/uu/sum/src/sum.rs
+++ b/src/uu/sum/src/sum.rs
@@ -19,9 +19,9 @@ use uucore::error::{FromIo, UResult, USimpleError};
 use uucore::InvalidEncodingHandling;
 
 static NAME: &str = "sum";
-static USAGE: &str =
-    "[OPTION]... [FILE]...\nWith no FILE, or when  FILE is -, read standard input.";
-static SUMMARY: &str = "Checksum and count the blocks in a file.";
+static USAGE: &str = "sum [OPTION]... [FILE]...";
+static SUMMARY: &str = "Checksum and count the blocks in a file.\n\
+                        With no FILE, or when  FILE is -, read standard input.";
 
 fn bsd_sum(mut reader: Box<dyn Read>) -> (usize, u16) {
     let mut buf = [0; 1024];
diff --git a/src/uu/unexpand/src/unexpand.rs b/src/uu/unexpand/src/unexpand.rs
index 83220a012..812375117 100644
--- a/src/uu/unexpand/src/unexpand.rs
+++ b/src/uu/unexpand/src/unexpand.rs
@@ -22,8 +22,8 @@ use uucore::InvalidEncodingHandling;
 
 static NAME: &str = "unexpand";
 static USAGE: &str = "unexpand [OPTION]... [FILE]...";
-static SUMMARY: &str = "Convert blanks in each FILE to tabs, writing to standard output.\n
-                 With no FILE, or when FILE is -, read standard input.";
+static SUMMARY: &str = "Convert blanks in each FILE to tabs, writing to standard output.\n\
+                        With no FILE, or when FILE is -, read standard input.";
 
 const DEFAULT_TABSTOP: usize = 8;