Merge pull request #3499 from epage/doc

docs(examples): Help smooth out some rought edges

Cargo.toml

@@ -309,6 +309,11 @@ name = "03_04_subcommands_derive"
 path = "examples/tutorial_derive/03_04_subcommands.rs"
 required-features = ["derive"]
 
+[[example]]
+name = "03_04_subcommands_alt_derive"
+path = "examples/tutorial_derive/03_04_subcommands_alt.rs"
+required-features = ["derive"]
+
 [[example]]
 name = "03_05_default_values_derive"
 path = "examples/tutorial_derive/03_05_default_values.rs"

examples/README.md

@@ -2,13 +2,28 @@
 
 - Basic demo: [derive](demo.md)
 - Key-value pair arguments: [derive](keyvalue-derive.md)
+  - Topics:
+    - Custom `parse()`
 - Custom cargo command: [builder](cargo-example.md), [derive](cargo-example-derive.md)
+  - Topics:
+    - Subcommands
+    - Cargo plugins
 - git-like interface: [builder](git.md), [derive](git-derive.md)
+  - Topics:
+    - Subcommands
+    - External subcommands
 - pacman-like interface: [builder](pacman.md)
+  - Topics:
+    - Flag subcommands
+    - Conflicting arguments
 - Escaped positionals with `--`: [builder](escaped-positional.md), [derive](escaped-positional-derive.md)
 - Multi-call
   - busybox: [builder](multicall-busybox.md)
+    - Topics:
+      - Subcommands
   - hostname: [builder](multicall-hostname.md)
+    - Topics:
+      - Subcommands
 
 ## Contributing
 

examples/derive_ref/README.md

@@ -16,7 +16,7 @@ To derive `clap` types, you need to enable the `derive` feature flag.
 
 See [demo.rs](../demo.rs) and [demo.md](../demo.md) for a brief example.
 
-Let's start by breaking down what can go where:
+Let's start by breaking down the anatomy of the derive attributes:
 ```rust
 use clap::{Parser, Args, Subcommand, ArgEnum};
 
@@ -78,6 +78,7 @@ fn main() {
 - `Parser` parses arguments into a `struct` (arguments) or `enum` (subcommands).
 - `Args` allows defining a set of re-usable arguments that get merged into their parent container.
 - `Subcommand` defines available subcommands.
+  - Subcommand arguments can be defined in a struct-variant or automatically flattened with a tuple-variant.
 - `ArgEnum` allows parsing a value directly into an `enum`, erroring on unsupported values.
 
 See also the [tutorial](../tutorial_derive/README.md) and [examples](../README.md).

examples/tutorial_builder/README.md

@@ -642,7 +642,8 @@ Doing work using input input.txt and config config.toml
 
 ## Tips
 
-- Proactively check for bad `Command` configurations by calling `Command::debug_assert` ([example](05_01_assert.rs))
+- For more complex demonstration of features, see our [examples](../README.md).
+- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs))
 
 ## Contributing
 

examples/tutorial_derive/03_04_subcommands_alt.rs

@@ -0,0 +1,32 @@
+use clap::{Args, Parser, Subcommand};
+
+#[derive(Parser)]
+#[clap(author, version, about, long_about = None)]
+#[clap(propagate_version = true)]
+struct Cli {
+    #[clap(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Adds files to myapp
+    Add(Add),
+}
+
+#[derive(Args)]
+struct Add {
+    name: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // You can check for the existence of subcommands, and if found use their
+    // matches just as you would the top level cmd
+    match &cli.command {
+        Commands::Add(name) => {
+            println!("'myapp add' was used, name is: {:?}", name.name)
+        }
+    }
+}

examples/tutorial_derive/README.md

@@ -306,6 +306,10 @@ $ 03_04_subcommands_derive add bob
 
 ```
 
+Above, we used a struct-variant to define the `add` subcommand.  Alternatively,
+you can
+[use a struct for your subcommand's arguments](03_04_subcommands_alt_derive.rs).
+
 Because we used `command: Commands` instead of `command: Option<Commands>`:
 ```console
 $ 03_04_subcommands_derive
@@ -610,7 +614,10 @@ Doing work using input input.txt and config config.toml
 
 ## Tips
 
-- Proactively check for bad `Command` configurations by calling `Command::debug_assert` ([example](05_01_assert.rs))
+- For more complex demonstration of features, see our [examples](../README.md).
+- See the [derive reference](../derive_ref/README.md) to understand how to use
+  anything in the [builder API](https://docs.rs/clap/) in the derive API.
+- Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs))
 
 ## Contributing