From 304e12bd8eda61e058fbbf94ea961b8c0035b0b4 Mon Sep 17 00:00:00 2001
From: a dinosaur <dino@a-dinosaur.com>
Date: Thu, 6 Nov 2025 02:29:06 +1100
Subject: [PATCH] Restrict scope of automatic usage hint in standard error
 writer, so the default behaviour is less spammy

---
 jaarg/src/help.rs | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/jaarg/src/help.rs b/jaarg/src/help.rs
index 84fad67..6de6e8b 100644
--- a/jaarg/src/help.rs
+++ b/jaarg/src/help.rs
@@ -209,18 +209,21 @@ impl<ID> core::fmt::Display for StandardErrorUsageWriter<'_, ID> {
     // Write error
     writeln!(f, "{name}: {error}", name=self.0.program_name, error = self.0.error)?;
 
-    // Write usage
-    writeln!(f, "{}", StandardShortUsageWriter::new(HelpWriterContext {
-      options: self.0.options,
-      program_name: self.0.program_name
-    }))?;
+    // Provide usage hint for missing required arguments
+    if matches!(self.0.error, ParseError::RequiredPositional(_) | ParseError::RequiredParameter(_)) {
+      // Write short usage
+      writeln!(f, "{}", StandardShortUsageWriter::new(HelpWriterContext {
+        options: self.0.options,
+        program_name: self.0.program_name
+      }))?;
 
-    // Write full help instruction if a
-    if let Some(help_option) = self.0.options.help_option() {
-      writeln!(f, "Run '{name} {help}' to view all available options.",
-        name = self.0.program_name,
-        // Prefer long name, but otherwise any name is fine
-        help = help_option.first_long_name().unwrap_or(help_option.first_name()))?;
+      // Write full help instruction if available
+      if let Some(help_option) = self.0.options.help_option() {
+        writeln!(f, "Run '{name} {help}' to view all available options.",
+          name = self.0.program_name,
+          // Prefer long name, but otherwise any name is fine
+          help = help_option.first_long_name().unwrap_or(help_option.first_name()))?;
+      }
     }
     Ok(())
   }