From 0f227f3aad67147995a7dbd7ef87fc7dd57247cc Mon Sep 17 00:00:00 2001 From: Alexander Fadeev Date: Mon, 16 Feb 2026 08:46:43 +0200 Subject: [PATCH 1/4] chore: add advanced command description and examples to goup --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++-- argh/examples/goup.rs | 40 ++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 argh/examples/goup.rs diff --git a/README.md b/README.md index 8a03f94..b11eb13 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ 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 @@ -174,7 +174,64 @@ struct SubCommandTwo { } ``` -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, + /// command to execute + #[argh(subcommand)] + pub command: Command, +} +``` + +Output: + +``` +Usage: goup --height [--pilot-nickname ] [] + +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 +``` + +## Note + +This is not an officially supported Google product. ## How to debug the expanded derive macro for `argh` diff --git a/argh/examples/goup.rs b/argh/examples/goup.rs new file mode 100644 index 0000000..68f4074 --- /dev/null +++ b/argh/examples/goup.rs @@ -0,0 +1,40 @@ +use argh::FromArgs; + +#[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, + /// command to execute + #[argh(subcommand)] + pub command: Command, +} + +#[derive(FromArgs, Debug)] +#[argh(subcommand)] +pub enum Command { + Jump(JumpCmd), +} + +#[derive(FromArgs, Debug)] +#[argh(subcommand, name = "jump", short = 'j')] +/// whether or not to jump +pub struct JumpCmd {} + +fn main() { + let args: CliArgs = argh::from_env(); + println!("{:#?}", args); +} From 7fdd2408a38714a0154e1b0556539438bc1f55f6 Mon Sep 17 00:00:00 2001 From: Alexander Fadeev Date: Tue, 17 Feb 2026 01:09:41 +0200 Subject: [PATCH 2/4] chore: add advanced command description and examples to `lib.rs` --- argh/src/lib.rs | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/argh/src/lib.rs b/argh/src/lib.rs index 7decc64..c2fa651 100644 --- a/argh/src/lib.rs +++ b/argh/src/lib.rs @@ -317,6 +317,60 @@ //! } //! ``` //! +//! You can define a complex help output that includes an **Examples** section. +//! Use a `{command_name}` placeholder. +//! +//! ```rust +//! # use argh::FromArgs; +//! #[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, +//! /// command to execute +//! #[argh(subcommand)] +//! pub command: Command, +//! } +//! ``` +//! +//! Output: +//! +//! ```text +//! Usage: goup --height [--pilot-nickname ] [] +//! +//! 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 From 38b016ec0396de1f375ec59e19dfaf7e91046a06 Mon Sep 17 00:00:00 2001 From: Alexander Fadeev Date: Fri, 20 Feb 2026 13:37:37 +0200 Subject: [PATCH 3/4] chore: move note about Google support to the end of README.md --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b11eb13..35d5879 100644 --- a/README.md +++ b/README.md @@ -229,11 +229,6 @@ Examples: goup --height 5 --pilot-nickname Wes jump ``` -## Note - -This is not an officially supported Google product. - - ## How to debug the expanded derive macro for `argh` The `argh::FromArgs` derive macro can be debugged with the [cargo-expand](https://crates.io/crates/cargo-expand) crate. @@ -245,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. From 14023d05312cb5a819b43273e6f5570971d43cc8 Mon Sep 17 00:00:00 2001 From: Alexander Fadeev Date: Wed, 4 Mar 2026 14:22:48 +0200 Subject: [PATCH 4/4] fix: the "unused warning" and doc tests --- argh/examples/goup.rs | 14 +++++++------- argh/src/lib.rs | 10 +++++++--- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/argh/examples/goup.rs b/argh/examples/goup.rs index 68f4074..d6d3d67 100644 --- a/argh/examples/goup.rs +++ b/argh/examples/goup.rs @@ -1,6 +1,6 @@ use argh::FromArgs; -#[derive(FromArgs, Debug)] +#[derive(FromArgs, PartialEq, Debug)] #[argh( description = "{command_name} is a tool to reach new heights.\n\n\ Start exploring new heights:\n\n\ @@ -11,7 +11,7 @@ use argh::FromArgs; {command_name} --height 5 j\n\ {command_name} --height 5 --pilot-nickname Wes jump" )] -pub struct CliArgs { +struct CliArgs { /// how high to go #[argh(option)] height: usize, @@ -20,19 +20,19 @@ pub struct CliArgs { pilot_nickname: Option, /// command to execute #[argh(subcommand)] - pub command: Command, + command: Command, } -#[derive(FromArgs, Debug)] +#[derive(FromArgs, PartialEq, Debug)] #[argh(subcommand)] -pub enum Command { +enum Command { Jump(JumpCmd), } -#[derive(FromArgs, Debug)] +#[derive(FromArgs, PartialEq, Debug)] #[argh(subcommand, name = "jump", short = 'j')] /// whether or not to jump -pub struct JumpCmd {} +struct JumpCmd {} fn main() { let args: CliArgs = argh::from_env(); diff --git a/argh/src/lib.rs b/argh/src/lib.rs index c2fa651..322214a 100644 --- a/argh/src/lib.rs +++ b/argh/src/lib.rs @@ -322,7 +322,7 @@ //! //! ```rust //! # use argh::FromArgs; -//! #[derive(FromArgs, Debug)] +//! #[derive(FromArgs, PartialEq, Debug)] //! #[argh( //! description = "{command_name} is a tool to reach new heights.\n\n\ //! Start exploring new heights:\n\n\ @@ -333,7 +333,7 @@ //! {command_name} --height 5 j\n\ //! {command_name} --height 5 --pilot-nickname Wes jump" //! )] -//! pub struct CliArgs { +//! struct CliArgs { //! /// how high to go //! #[argh(option)] //! height: usize, @@ -342,8 +342,12 @@ //! pilot_nickname: Option, //! /// command to execute //! #[argh(subcommand)] -//! pub command: Command, +//! command: Command, //! } +//! +//! # #[derive(FromArgs, PartialEq, Debug)] +//! # #[argh(subcommand)] +//! # enum Command {} //! ``` //! //! Output: