Merge pull request #6012 from epage/sub

docs(derive): Specify arg_required_else_help is set for users

Author: epage

examples/tutorial_builder/03_04_subcommands.md

@@ -29,7 +29,10 @@ $ 03_04_subcommands add bob
 
 ```
 
-Because we set [`Command::arg_required_else_help`][crate::Command::arg_required_else_help]:
+We set
+[`Command::arg_required_else_help`][crate::Command::arg_required_else_help] to
+show the help, rather than an error, when the
+[required subcommand][crate::Command::subcommand_required] is missing:
 ```console
 $ 03_04_subcommands
 ? failed

examples/tutorial_derive/03_04_subcommands.md

@@ -29,8 +29,8 @@ $ 03_04_subcommands_derive add bob
 
 ```
 
-When specifying commands with `command: Commands`, they are required.
-Alternatively, you could do `command: Option<Commands>` to make it optional.
+When specifying commands with `command: Commands`, they are [required][crate::Command::subcommand_required].
+By default, a missing subcommand will [show help rather than error][crate::Command::arg_required_else_help].
 ```console
 $ 03_04_subcommands_derive
 ? failed
@@ -47,6 +47,7 @@ Options:
   -V, --version  Print version
 
 ```
+To make a subcommand optional, wrap it in an `Option` (e.g. `command: Option<Commands>`).
 
 Since we specified [`#[command(propagate_version = true)]`][crate::Command::propagate_version],
 the `--version` flag is available in all subcommands:

src/_derive/mod.rs

@@ -8,7 +8,7 @@
 //!     3. [Arg Attributes](#arg-attributes)
 //!     4. [ValueEnum Attributes](#valueenum-attributes)
 //!     5. [Possible Value Attributes](#possible-value-attributes)
-//! 3. [Arg Types](#arg-types)
+//! 3. [Field Types](#field-types)
 //! 4. [Doc Comments](#doc-comments)
 //! 5. [Mixing Builder and Derive APIs](#mixing-builder-and-derive-apis)
 //! 6. [Tips](#tips)
@@ -294,9 +294,18 @@
 //!   - When not present: [Doc comment summary](#doc-comments)
 //! - `skip`: Ignore this variant
 //!
-//! ## Arg Types
+//! ## Field Types
 //!
-//! `clap` assumes some intent based on the type used:
+//! `clap` assumes some intent based on the type used.
+//!
+//! ### Subcommand Types
+//!
+//! | Type                  | Effect              | Implies                                                   |
+//! |-----------------------|---------------------|-----------------------------------------------------------|
+//! | `Option<T>`           | optional subcommand |                                                           |
+//! | `T`                   | required subcommand | `.subcommand_required(true).arg_required_else_help(true)` |
+//!
+//! ### Arg Types
 //!
 //! | Type                  | Effect                                               | Implies                                                     | Notes |
 //! |-----------------------|------------------------------------------------------|-------------------------------------------------------------|-------|