fix: Deprecate SubcommandRequiredElseHelp

Now that 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.

Issue clap-rs#3280 will see the derive updated

clap_derive/src/derives/args.rs

@@ -168,6 +168,7 @@ pub fn gen_augment(
                 quote!()
             } else {
                 quote_spanned! { kind.span()=>
+                    #[allow(deprecated)]
                     let #app_var = #app_var.setting(
                         clap::AppSettings::SubcommandRequiredElseHelp
                     );

clap_derive/src/derives/into_app.rs

@@ -103,6 +103,7 @@ pub fn gen_for_enum(enum_name: &Ident, generics: &Generics, attrs: &[Attribute])
         #[deny(clippy::correctness)]
         impl #impl_generics clap::IntoApp for #enum_name #ty_generics #where_clause {
             fn into_app<'b>() -> clap::App<'b> {
+                #[allow(deprecated)]
                 let #app_var = clap::App::new(#name)
                     .setting(clap::AppSettings::SubcommandRequiredElseHelp);
                 <Self as clap::Subcommand>::augment_subcommands(#app_var)

clap_derive/src/derives/subcommand.rs

@@ -248,6 +248,7 @@ fn gen_augment(
                             let #subcommand_var = clap::App::new(#name);
                             let #subcommand_var = #subcommand_var #initial_app_methods;
                             let #subcommand_var = #arg_block;
+                            #[allow(deprecated)]
                             let #subcommand_var = #subcommand_var.setting(clap::AppSettings::SubcommandRequiredElseHelp);
                             #subcommand_var #final_from_attrs
                         });

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))
 }
 

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

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()
             {

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(

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")