api(App): Adds help_about method to App.

Help about text is now customizable and propagates to subcommands. Closes #2080.

src/build/app/mod.rs

@@ -83,6 +83,7 @@ pub struct App<'help> {
     pub(crate) long_version: Option<&'help str>,
     pub(crate) about: Option<&'help str>,
     pub(crate) long_about: Option<&'help str>,
+    pub(crate) help_about: Option<&'help str>,
     pub(crate) before_help: Option<&'help str>,
     pub(crate) before_long_help: Option<&'help str>,
     pub(crate) after_help: Option<&'help str>,
@@ -420,6 +421,29 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Sets the help text for the auto-generated help argument and subcommand.
+    ///
+    /// By default clap sets this to "Prints help information" for the help
+    /// argument and "Prints this message or the help of the given subcommand(s)"
+    /// for the help subcommand but if you're using a different convention
+    /// for your help messages and would prefer a different phrasing you can
+    /// override it.
+    ///
+    /// **NOTE:** This setting propagates to subcommands.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap::App;
+    /// App::new("myprog")
+    ///     .help_about("Print help information") // Impertive tone
+    /// # ;
+    /// ```
+    pub fn help_about<S: Into<&'help str>>(mut self, help_about: S) -> Self {
+        self.help_about = Some(help_about.into());
+        self
+    }
+
     /// (Re)Sets the program's name. This will be displayed when displaying help
     /// or version messages.
     ///
@@ -2247,6 +2271,9 @@ impl<'help> App<'help> {
                     $sc.g_settings = $sc.g_settings | $_self.g_settings;
                     $sc.term_w = $_self.term_w;
                     $sc.max_w = $_self.max_w;
+                    if $sc.help_about.is_none() && $_self.help_about.is_some() {
+                        $sc.help_about = $_self.help_about.clone();
+                    }
                 }
                 {
                     // FIXME: This doesn't belong here at all.
@@ -2299,7 +2326,7 @@ impl<'help> App<'help> {
             debug!("App::_create_help_and_version: Building --help");
             let mut help = Arg::new("help")
                 .long("help")
-                .about("Prints help information");
+                .about(self.help_about.unwrap_or("Prints help information"));
             if !self.args.args.iter().any(|x| x.short == Some('h')) {
                 help = help.short('h');
             }
@@ -2333,8 +2360,10 @@ impl<'help> App<'help> {
         {
             debug!("App::_create_help_and_version: Building help");
             self.subcommands.push(
-                App::new("help")
+                App::new("help").about(
-                    .about("Prints this message or the help of the given subcommand(s)"),
+                    self.help_about
+                        .unwrap_or("Prints this message or the help of the given subcommand(s)"),
+                ),
             );
         }
     }

tests/help.rs

@@ -1825,3 +1825,155 @@ fn after_help_no_args() {
 
     assert_eq!(help, AFTER_HELP_NO_ARGS);
 }
+
+static HELP_ABOUT: &str = "myapp 1.0
+
+USAGE:
+    myapp
+
+FLAGS:
+    -h, --help       Print custom help about text
+    -V, --version    Prints version information";
+
+static HELP_ABOUT_MULTI_SC: &str = "myapp-subcmd-multi 1.0
+
+USAGE:
+    myapp subcmd multi
+
+FLAGS:
+    -h, --help       Print custom help about text
+    -V, --version    Prints version information";
+
+static HELP_ABOUT_MULTI_SC_OVERRIDE: &str = "myapp-subcmd-multi 1.0
+
+USAGE:
+    myapp subcmd multi
+
+FLAGS:
+    -h, --help       Print custom help about text from multi
+    -V, --version    Prints version information";
+
+#[test]
+fn help_about_short_flag() {
+    let app = App::new("myapp")
+        .version("1.0")
+        .help_about("Print custom help about text");
+
+    assert!(utils::compare_output(app, "myapp -h", HELP_ABOUT, false));
+}
+
+#[test]
+fn help_about_long_flag() {
+    let app = App::new("myapp")
+        .version("1.0")
+        .help_about("Print custom help about text");
+
+    assert!(utils::compare_output(
+        app,
+        "myapp --help",
+        HELP_ABOUT,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
+
+    assert!(utils::compare_output(
+        app,
+        "myapp help subcmd multi",
+        HELP_ABOUT_MULTI_SC,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd_short_flag() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
+
+    assert!(utils::compare_output(
+        app,
+        "myapp subcmd multi -h",
+        HELP_ABOUT_MULTI_SC,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd_long_flag() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0")));
+
+    assert!(utils::compare_output(
+        app,
+        "myapp subcmd multi --help",
+        HELP_ABOUT_MULTI_SC,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd_override() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(
+            App::new("subcmd").subcommand(
+                App::new("multi")
+                    .version("1.0")
+                    .help_about("Print custom help about text from multi"),
+            ),
+        );
+
+    assert!(utils::compare_output(
+        app,
+        "myapp help subcmd multi",
+        HELP_ABOUT_MULTI_SC_OVERRIDE,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd_override_short_flag() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(
+            App::new("subcmd").subcommand(
+                App::new("multi")
+                    .version("1.0")
+                    .help_about("Print custom help about text from multi"),
+            ),
+        );
+
+    assert!(utils::compare_output(
+        app,
+        "myapp subcmd multi -h",
+        HELP_ABOUT_MULTI_SC_OVERRIDE,
+        false
+    ));
+}
+
+#[test]
+fn help_about_multi_subcmd_override_long_flag() {
+    let app = App::new("myapp")
+        .help_about("Print custom help about text")
+        .subcommand(
+            App::new("subcmd").subcommand(
+                App::new("multi")
+                    .version("1.0")
+                    .help_about("Print custom help about text from multi"),
+            ),
+        );
+
+    assert!(utils::compare_output(
+        app,
+        "myapp subcmd multi --help",
+        HELP_ABOUT_MULTI_SC_OVERRIDE,
+        false
+    ));
+}