fix: tweak usage output

jdx · Sep 28, 2024 · c488b76 · c488b76
1 parent ac745d6
commit c488b76
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 24 deletions.
diff --git a/lib/src/docs/markdown/cmd.rs b/lib/src/docs/markdown/cmd.rs
@@ -23,7 +23,7 @@ mod tests {
     fn test_render_markdown_cmd() {
         let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK).with_multi(true);
         assert_snapshot!(ctx.render_cmd(&SPEC_KITCHEN_SINK.cmd).unwrap(), @r####"
-        # `mycli [args] [flags] [subcommand]`
+        # `mycli [flags] <args>… [subcommand]`
 
         ## Arguments
 

diff --git a/lib/src/docs/markdown/spec.rs b/lib/src/docs/markdown/spec.rs
@@ -31,7 +31,7 @@ mod tests {
     fn test_render_markdown_spec() {
         let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK);
         assert_snapshot!(ctx.render_spec().unwrap(), @r#####"
-        # `mycli [args] [flags] [subcommand]`
+        # `mycli [flags] <args>… [subcommand]`
 
         ## Arguments
 
@@ -67,7 +67,7 @@ mod tests {
 
         ## `mycli plugin [subcommand]`
 
-        ## `mycli plugin install [args] [flags]`
+        ## `mycli plugin install [flags] <plugin> <version>`
 
         ### Arguments
 

diff --git a/lib/src/spec/cmd.rs b/lib/src/spec/cmd.rs
@@ -208,27 +208,36 @@ impl SpecCommand {
     }
     pub fn usage(&self) -> String {
         let mut usage = self.full_cmd.join(" ");
-        let total_count = self.args.len() + self.flags.len();
-        if self.subcommands.is_empty() && total_count <= 2 {
-            let inlines = self
-                .args
-                .iter()
-                .filter(|a| !a.hide)
-                .map(|a| a.usage())
-                .chain(
-                    self.flags
-                        .iter()
-                        .filter(|f| !f.hide)
-                        .map(|f| format!("[{f}]")),
-                )
-                .join(" ");
-            return format!("{usage} {inlines}").trim().to_string();
-        }
-        if !self.args.is_empty() {
-            usage = format!("{usage} [args]");
-        }
-        if !self.flags.is_empty() {
-            usage = format!("{usage} [flags]");
+        let flags = self.flags.iter().filter(|f| !f.hide).collect_vec();
+        let args = self.args.iter().filter(|a| !a.hide).collect_vec();
+        if !flags.is_empty() {
+            if flags.len() <= 2 {
+                let inlines = flags
+                    .iter()
+                    .map(|f| {
+                        if f.required {
+                            format!("<{}>", f.usage())
+                        } else {
+                            format!("[{}]", f.usage())
+                        }
+                    })
+                    .join(" ");
+                usage = format!("{usage} {inlines}").trim().to_string();
+            } else if flags.iter().any(|f| f.required) {
+                usage = format!("{usage} <flags>");
+            } else {
+                usage = format!("{usage} [flags]");
+            }
+        }
+        if !args.is_empty() {
+            if args.len() <= 2 {
+                let inlines = args.iter().map(|a| a.usage()).join(" ");
+                usage = format!("{usage} {inlines}").trim().to_string();
+            } else if args.iter().any(|a| a.required) {
+                usage = format!("{usage} <args>…");
+            } else {
+                usage = format!("{usage} [args]…");
+            }
         }
         // TODO: mounts?
         // if !self.mounts.is_empty() {