Merge pull request #5121 from epage/docs

docs(tutorial): Try to clean up the text

examples/tutorial_builder/03_04_subcommands.md

@@ -47,7 +47,8 @@ Options:
 
 ```
 
-Because we set [`Command::propagate_version`][crate::Command::propagate_version]:
+Since we specified [`Command::propagate_version`][crate::Command::propagate_version], the `--version` flag
+is available in all subcommands:
 ```console
 $ 03_04_subcommands --version
 clap [..]

examples/tutorial_derive/03_04_subcommands.md

@@ -29,7 +29,8 @@ $ 03_04_subcommands_derive add bob
 
 ```
 
-Because we used `command: Commands` instead of `command: Option<Commands>`:
+When specifying commands with `command: Commands`, they are required.
+Alternatively, you could do `commaand: Option<Commands>` to make it optional.
 ```console
 $ 03_04_subcommands_derive
 ? failed
@@ -47,7 +48,8 @@ Options:
 
 ```
 
-Because we added `#[command(propagate_version = true)]`:
+Since we specified [`#[command(propagate_version = true)]`][crate::Command::propagate_version],
+the `--version` flag is available in all subcommands:
 ```console
 $ 03_04_subcommands_derive --version
 clap [..]

src/_derive/_tutorial.rs

@@ -55,14 +55,14 @@
 //!
 #![doc = include_str!("../../examples/tutorial_derive/02_apps.md")]
 //!
-//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] to fill these fields in from your `Cargo.toml` file.
+//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] on the struct to fill these fields in from your `Cargo.toml` file.
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")]
 //! ```
 #![doc = include_str!("../../examples/tutorial_derive/02_crate.md")]
 //!
-//! You can use attributes to change the application level behavior of clap.  Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
+//! You can use `#[command]` attributes on the struct to change the application level behavior of clap.  Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")]
@@ -71,6 +71,8 @@
 //!
 //! ## Adding Arguments
 //!
+//! Arguments are inferred from the fields of your struct.
+//!
 //! ### Positionals
 //!
 //! You can have users specify values by their position on the command-line:
@@ -94,9 +96,9 @@
 //! - They can be optional
 //! - Intent is clearer
 //!
-//! The [`#[arg(short = 'n')]`][Arg::short] and [`#[arg(long = "name")]`][Arg::long] attributes that define
-//! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value
-//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]).
+//! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
+//! [`#[arg(long = "name")]`][Arg::long] attributes on a field.  When no value is given (e.g.
+//! `#[arg(short)]`), the flag is inferred from the field's name.
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")]
@@ -128,11 +130,14 @@
 //! ```
 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.md")]
 //!
+//! This also shows that any[`Arg`][crate::Args] method may be used as an attribute.
+//!
 //! ### Subcommands
 //!
-//! Subcommands are derived with `#[derive(Subcommand)]` and be added via [`#[command(subcommand)]` attribute][super#command-attributes]. Each
-//! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own
-//! subcommands.
+//! Subcommands are derived with `#[derive(Subcommand)]` and be added via
+//! [`#[command(subcommand)]` attribute][super#command-attributes] on the field using that type.
+//! Each instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args,
+//! and even its own subcommands.
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")]
@@ -165,7 +170,7 @@
 //!
 //! For example, if you have arguments of specific values you want to test for, you can derive
 //! [`ValueEnum`][super#valueenum-attributes]
-//! (any [`PossibleValue`] builder function can be used as variant attributes).
+//! (any [`PossibleValue`] builder function can be used as a `#[value]` attribute on enum variants).
 //!
 //! This allows you specify the valid values for that argument. If the user does not use one of
 //! those specific values, they will receive a graceful exit with error message informing them