From 1c0e079340398c5258bab851120a71c334dd1217 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Fri, 11 Feb 2022 15:16:36 -0600
Subject: [PATCH] fix: Deprecate SubcommandRequiredElseHelp

With #3280 resolved where we can use `SubcommandRequired |
ArgRequiredElseHelp`, this setting offers little value but requires we
track required subcommands with two different settings.  Deprecating as
the cost is not worth the benefit anymore.
---
 clap_mangen/src/render.rs     |  1 +
 src/build/app_settings.rs     | 25 ++++++-------------------
 src/output/usage.rs           |  1 +
 src/parse/validator.rs        |  1 +
 tests/builder/app_settings.rs |  2 ++
 5 files changed, 11 insertions(+), 19 deletions(-)

diff --git a/clap_mangen/src/render.rs b/clap_mangen/src/render.rs
index ced17bcdeea..1515450ed1f 100644
--- a/clap_mangen/src/render.rs
+++ b/clap_mangen/src/render.rs
@@ -176,6 +176,7 @@ pub(crate) fn after_help(roff: &mut Roff, app: &clap::App) {
 }
 
 fn subcommand_markers(cmd: &clap::App) -> (&'static str, &'static str) {
+    #[allow(deprecated)]
     markers(cmd.is_subcommand_required_set() || cmd.is_set(AppSettings::SubcommandRequiredElseHelp))
 }
 
diff --git a/src/build/app_settings.rs b/src/build/app_settings.rs
index db3735da9fc..d8e8e0b30c0 100644
--- a/src/build/app_settings.rs
+++ b/src/build/app_settings.rs
@@ -132,25 +132,12 @@ pub enum AppSettings {
     )]
     SubcommandRequired,
 
-    /// Display help if no [`subcommands`] are present at runtime and exit gracefully (i.e. an
-    /// empty run such as `$ myprog`).
-    ///
-    /// **NOTE:** This should *not* be used with [`AppSettings::SubcommandRequired`] as they do
-    /// nearly same thing; this prints the help text, and the other prints an error.
-    ///
-    /// **NOTE:** If the user specifies arguments at runtime, but no subcommand the help text will
-    /// still be displayed and exit. If this is *not* the desired result, consider using
-    /// [`AppSettings::ArgRequiredElseHelp`] instead.
-    ///
-    /// # Examples
-    ///
-    /// ```rust
-    /// # use clap::{App, Arg, AppSettings};
-    /// App::new("myprog")
-    ///     .setting(AppSettings::SubcommandRequiredElseHelp);
-    /// ```
-    ///
-    /// [`subcommands`]: crate::App::subcommand()
+    /// Deprecated, replaced with [`App::subcommand_required`] combined with
+    /// [`App::arg_required_else_help`].
+    #[deprecated(
+        since = "3.1.0",
+        note = "Replaced with `App::subcommand_required` combined with `App::arg_required_else_help`"
+    )]
     SubcommandRequiredElseHelp,
 
     /// Deprecated, replaced with [`App::allow_external_subcommands`] and
diff --git a/src/output/usage.rs b/src/output/usage.rs
index f8e1650e7e9..2da807c305c 100644
--- a/src/output/usage.rs
+++ b/src/output/usage.rs
@@ -123,6 +123,7 @@ impl<'help, 'app> Usage<'help, 'app> {
             || self.app.is_allow_external_subcommands_set()
         {
             let placeholder = self.app.subcommand_value_name.unwrap_or("SUBCOMMAND");
+            #[allow(deprecated)]
             if self.app.is_subcommand_negates_reqs_set()
                 || self.app.is_args_conflicts_with_subcommands_set()
             {
diff --git a/src/parse/validator.rs b/src/parse/validator.rs
index aba2888b0f6..7035fa971ac 100644
--- a/src/parse/validator.rs
+++ b/src/parse/validator.rs
@@ -61,6 +61,7 @@ impl<'help, 'app, 'parser> Validator<'help, 'app, 'parser> {
                 return Err(Error::display_help_error(self.p.app, message));
             }
         }
+        #[allow(deprecated)]
         if !has_subcmd && self.p.app.is_subcommand_required_set() {
             let bn = self.p.app.bin_name.as_ref().unwrap_or(&self.p.app.name);
             return Err(Error::missing_subcommand(
diff --git a/tests/builder/app_settings.rs b/tests/builder/app_settings.rs
index 68056337278..d7252cf1749 100644
--- a/tests/builder/app_settings.rs
+++ b/tests/builder/app_settings.rs
@@ -260,6 +260,7 @@ fn arg_required_else_help_error_message() {
 
 #[test]
 fn subcommand_required_else_help() {
+    #![allow(deprecated)]
     let result = App::new("test")
         .setting(AppSettings::SubcommandRequiredElseHelp)
         .subcommand(App::new("info"))
@@ -275,6 +276,7 @@ fn subcommand_required_else_help() {
 
 #[test]
 fn subcommand_required_else_help_error_message() {
+    #![allow(deprecated)]
     let app = App::new("test")
         .setting(AppSettings::SubcommandRequiredElseHelp)
         .version("1.0")