Repository: clap-rs/clap (rust)

Issue:
docs(derive): Clarify that `arg_required_else_help(true)` is implicitly set when they define the required subcommand
If they define the required subcommand (`command: Commands`), `arg_required_else_help(true)` and `subcommand_required(true)` are implicitly set.

It has already been described in the documentation that `command: Commands` defines the required subcommand and `command: Option<Commands>` defines the optional subcommand. This is also evident from these types. So I don't think there is any need to describe `subcommand_required`.

I've searched the documentation, but at least in <https://docs.rs/clap/4.5.38/clap/_derive/index.html#command-attributes> and <https://docs.rs/clap/4.5.38/clap/_derive/_tutorial/index.html#subcommands>, I couldn't find any description about `arg_required_else_help(true)` being implicitly set. I didn't know that `arg_required_else_help(true)` is implicitly set until I read #3280 and #3721. I initially thought that if the required subcommand didn't exist, an error message would be displayed instead of a help message.

So I think it would be better to clarify in the documentation that `arg_required_else_help(true)` is implicitly set when they define the required subcommand (`command: Commands`).

Pull request:
docs(derive): Specify arg_required_else_help is set for users
Fixes #6001

<!--
Thanks for helping out!

Please link the appropriate issue from your PR.

If you don't have an issue, we'd recommend starting with one first so the PR can focus on the
implementation (unless its an obvious bug or documentation fix that will have
little conversation).
-->


Patch:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e501191d..02dfaa1a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -164,7 +164,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.87"  # STABLE
+        toolchain: "1.86"  # STABLE
     - uses: Swatinem/rust-cache@v2
     - name: UI Tests
       run: make test-ui-${{ matrix.features }}
@@ -207,7 +207,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.87"  # STABLE
+        toolchain: "1.86"  # STABLE
     - uses: Swatinem/rust-cache@v2
     - name: Check documentation
       env:
@@ -222,7 +222,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.87"  # STABLE
+        toolchain: "1.86"  # STABLE
         components: rustfmt
     - uses: Swatinem/rust-cache@v2
     - name: Check formatting
@@ -236,7 +236,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.87"  # STABLE
+        toolchain: "1.86"  # STABLE
         components: clippy
     - uses: Swatinem/rust-cache@v2
     - name: Lint (ultra-minimal)
diff --git a/Makefile b/Makefile
index 5e62de8c..378ee772 100644
--- a/Makefile
+++ b/Makefile
@@ -10,7 +10,7 @@ ifneq (${TOOLCHAIN_TARGET},)
   ARGS+=--target ${TOOLCHAIN_TARGET}
 endif
 
-STABLE?=1.87
+STABLE?=1.86
 
 _FEATURES = minimal default wasm full debug release
 _FEATURES_minimal = --no-default-features --features "std"
diff --git a/examples/tutorial_builder/03_04_subcommands.md b/examples/tutorial_builder/03_04_subcommands.md
index a32b7768..24d44889 100644
--- a/examples/tutorial_builder/03_04_subcommands.md
+++ b/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
diff --git a/examples/tutorial_derive/03_04_subcommands.md b/examples/tutorial_derive/03_04_subcommands.md
index 4d57dfee..3ae06774 100644
--- a/examples/tutorial_derive/03_04_subcommands.md
+++ b/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:
diff --git a/src/_derive/mod.rs b/src/_derive/mod.rs
index b9091d2a..b49d0dbd 100644
--- a/src/_derive/mod.rs
+++ b/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 |
 //! |-----------------------|------------------------------------------------------|-------------------------------------------------------------|-------|


Test patch:
diff --git a/tests/derive_ui.rs b/tests/derive_ui.rs
index d06f69fb..9652bd5b 100644
--- a/tests/derive_ui.rs
+++ b/tests/derive_ui.rs
@@ -8,7 +8,7 @@
 #![cfg(feature = "unstable-derive-ui-tests")]
 
 #[cfg(feature = "derive")]
-#[rustversion::attr(not(stable(1.87)), ignore)] // STABLE
+#[rustversion::attr(not(stable(1.86)), ignore)] // STABLE
 #[test]
 fn ui() {
     let t = trybuild::TestCases::new();