From 57791b1a93f73b0608d7e4a09846c9d743878c81 Mon Sep 17 00:00:00 2001
From: a dinosaur <dino@a-dinosaur.com>
Date: Sun, 2 Nov 2025 02:01:05 +1100
Subject: [PATCH] Add program description to full help

---
 examples/bin2h.rs |  3 ++-
 src/help.rs       |  5 +++++
 src/options.rs    | 18 +++++++++++++++---
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/examples/bin2h.rs b/examples/bin2h.rs
index beefa34..367847e 100644
--- a/examples/bin2h.rs
+++ b/examples/bin2h.rs
@@ -208,7 +208,8 @@ pub fn main() -> ExitCode {
     Opt::value(Arg::Bin, &["--bin", "-b"], "data.bin").help_text("Add a binary file"),
     Opt::value(Arg::Txt, &["--txt", "-t"], "text.txt").help_text("Add a text file"),
     Opt::value(Arg::Whitespace, &["--whitespace"], "\"  \"").help_text("Emitted indentation (Default: \"\\t\")"),
-  ]);
+  ]).with_description("Convert one or more binary and text file(s) to a C header file,\n\
+                       as arrays and C strings respectively.");
   match OPTIONS.parse_easy(|program_name, id, _opt, _name, arg| {
     match id {
       Arg::Out => { arguments.out = arg.into(); }
diff --git a/src/help.rs b/src/help.rs
index cfd8073..5c8e5a4 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -110,6 +110,11 @@ impl<ID> core::fmt::Display for StandardFullHelpWriter<'_, ID> {
     }
     writeln!(f)?;
 
+    if let Some(description) = self.0.options.description {
+      writeln!(f)?;
+      writeln!(f, "{description}")?;
+    }
+
     fn calculate_left_pad<ID: 'static>(option: &Opt<ID>) -> usize {
       (match option.names {
         OptIdentifier::Single(name) => name.chars().count(),
diff --git a/src/options.rs b/src/options.rs
index 1e64faf..d63f64c 100644
--- a/src/options.rs
+++ b/src/options.rs
@@ -5,16 +5,22 @@
 
 /// Static structure that contains instructions for parsing command-line arguments
 pub struct Opts<ID: 'static> {
-  /// String containing single characters that match option prefixes
-  flag_chars: &'static str,
   /// List of options
   options: &'static[Opt<ID>],
+  /// String containing single characters that match option prefixes
+  flag_chars: &'static str,
+  /// A description of what the program does
+  description: Option<&'static str>,
 }
 
 impl<ID: 'static> Opts<ID> {
   /// Build argument parser options with the default flag character of '-'
   pub const fn new(options: &'static[Opt<ID>]) -> Self {
-    Self { flag_chars: "-", options }
+    Self {
+      options,
+      flag_chars: "-",
+      description: None,
+    }
   }
 
   /// Set the recognised flag/option characters.
@@ -22,4 +28,10 @@ impl<ID: 'static> Opts<ID> {
     self.flag_chars = flag_chars;
     self
   }
+
+  /// Set the description of the program, available to help writers.
+  pub const fn with_description(mut self, description: &'static str) -> Self {
+    self.description = Some(description);
+    self
+  }
 }