Enhance README/lib.rs with advanced command description examples

README.md

@@ -166,16 +166,68 @@ struct SubCommandOne {
 
 #[derive(FromArgs, PartialEq, Debug)]
 /// Second subcommand.
-#[argh(subcommand, name = "two")]
+#[argh(subcommand, name = "two", short = "t")]
 struct SubCommandTwo {
     #[argh(switch)]
     /// whether to fooey
     fooey: bool,
 }
 ```
 
-NOTE: This is not an officially supported Google product.
+## Advanced Description
 
+You can define a complex help output that includes an **Examples** section.
+Use a `{command_name}` placeholder.
+
+```rust
+#[derive(FromArgs, Debug)]
+#[argh(
+    description = "{command_name} is a tool to reach new heights.\n\n\
+    Start exploring new heights:\n\n\
+    \u{00A0} {command_name} --height 5 jump\n\
+    ",
+    example = "\
+    {command_name} --height 5\n\
+    {command_name} --height 5 j\n\
+    {command_name} --height 5 --pilot-nickname Wes jump"
+)]
+pub struct CliArgs {
+    /// how high to go
+    #[argh(option)]
+    height: usize,
+    /// an optional nickname for the pilot
+    #[argh(option)]
+    pilot_nickname: Option<String>,
+    /// command to execute
+    #[argh(subcommand)]
+    pub command: Command,
+}
+```
+
+Output:
+
+```
+Usage: goup --height <height> [--pilot-nickname <pilot-nickname>] <command> [<args>]
+
+goup is a tool to reach new heights.
+
+Start exploring new heights:
+
+  goup --height 5 jump
+
+Options:
+  --height          how high to go
+  --pilot-nickname  an optional nickname for the pilot
+  --help, help      display usage information
+
+Commands:
+  jump  j           whether or not to jump
+
+Examples:
+  goup --height 5
+  goup --height 5 j
+  goup --height 5 --pilot-nickname Wes jump
+```
 
 ## How to debug the expanded derive macro for `argh`
 
@@ -188,3 +240,7 @@ See [argh/examples/simple_example.rs](./argh/examples/simple_example.rs) for the
 First, install `cargo-expand` by running `cargo install cargo-expand`. Note this requires the nightly build of Rust.
 
 Once installed, run `cargo expand` with in the `argh` package and you can see the expanded code.
+
+## Note
+
+This is not an officially supported Google product.

argh/examples/goup.rs

@@ -0,0 +1,40 @@
+use argh::FromArgs;
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(
+    description = "{command_name} is a tool to reach new heights.\n\n\
+    Start exploring new heights:\n\n\
+    \u{00A0} {command_name} --height 5 jump\n\
+    ",
+    example = "\
+    {command_name} --height 5\n\
+    {command_name} --height 5 j\n\
+    {command_name} --height 5 --pilot-nickname Wes jump"
+)]
+struct CliArgs {
+    /// how high to go
+    #[argh(option)]
+    height: usize,
+    /// an optional nickname for the pilot
+    #[argh(option)]
+    pilot_nickname: Option<String>,
+    /// command to execute
+    #[argh(subcommand)]
+    command: Command,
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand)]
+enum Command {
+    Jump(JumpCmd),
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "jump", short = 'j')]
+/// whether or not to jump
+struct JumpCmd {}
+
+fn main() {
+    let args: CliArgs = argh::from_env();
+    println!("{:#?}", args);
+}

argh/src/lib.rs

@@ -317,6 +317,64 @@
 //! }
 //! ```
 //!
+//! You can define a complex help output that includes an **Examples** section.
+//! Use a `{command_name}` placeholder.
+//!
+//! ```rust
+//! # use argh::FromArgs;
+//! #[derive(FromArgs, PartialEq, Debug)]
+//! #[argh(
+//!     description = "{command_name} is a tool to reach new heights.\n\n\
+//!     Start exploring new heights:\n\n\
+//!     \u{00A0} {command_name} --height 5 jump\n\
+//!     ",
+//!     example = "\
+//!     {command_name} --height 5\n\
+//!     {command_name} --height 5 j\n\
+//!     {command_name} --height 5 --pilot-nickname Wes jump"
+//! )]
+//! struct CliArgs {
+//!     /// how high to go
+//!     #[argh(option)]
+//!     height: usize,
+//!     /// an optional nickname for the pilot
+//!     #[argh(option)]
+//!     pilot_nickname: Option<String>,
+//!     /// command to execute
+//!     #[argh(subcommand)]
+//!     command: Command,
+//! }
+//!
+//! # #[derive(FromArgs, PartialEq, Debug)]
+//! # #[argh(subcommand)]
+//! # enum Command {}
+//! ```
+//!
+//! Output:
+//!
+//! ```text
+//! Usage: goup --height <height> [--pilot-nickname <pilot-nickname>] <command> [<args>]
+//!
+//! goup is a tool to reach new heights.
+//!
+//! Start exploring new heights:
+//!
+//!   goup --height 5 jump
+//!
+//! Options:
+//!   --height          how high to go
+//!   --pilot-nickname  an optional nickname for the pilot
+//!   --help, help      display usage information
+//!
+//! Commands:
+//!   jump  j           whether or not to jump
+//!
+//! Examples:
+//!   goup --height 5
+//!   goup --height 5 j
+//!   goup --height 5 --pilot-nickname Wes jump
+//! ```
+//!
 //! Programs that are run from an environment such as cargo may find it
 //! useful to have positional arguments present in the structure but
 //! omitted from the usage output. This can be accomplished by adding