Merge #2878

2878: fix: Give Arg::help_heading priority over App::help_heading r=pksunkara a=epage



Co-authored-by: Ed Page <eopage@gmail.com>

src/build/app/mod.rs

@@ -1086,23 +1086,20 @@ impl<'help> App<'help> {
     /// [argument]: Arg
     pub fn arg<A: Into<Arg<'help>>>(mut self, a: A) -> Self {
         let mut arg = a.into();
-        if let Some(help_heading) = self.current_help_heading {
+        arg.help_heading.get_or_insert(self.current_help_heading);
-            arg = arg.help_heading(Some(help_heading));
-        }
         self.args.push(arg);
         self
     }
 
-    /// Set a custom section heading for future args. Every call to [`App::arg`]
+    /// Set the default section heading for future args.
-    /// (and its related methods) will use this header (instead of the default
+    ///
-    /// header for the specified argument type) until a subsequent call to
+    /// This will be used for any arg that hasn't had [`Arg::help_heading`] called.
-    /// [`App::help_heading`].
     ///
     /// This is useful if the default `OPTIONS` or `ARGS` headings are
     /// not specific enough for one's use case.
     ///
     /// [`App::arg`]: App::arg()
-    /// [`App::help_heading`]: App::help_heading()
+    /// [`Arg::help_heading`]: crate::Arg::help_heading()
     #[inline]
     pub fn help_heading<O>(mut self, heading: O) -> Self
     where

src/build/arg/mod.rs

@@ -118,7 +118,7 @@ pub struct Arg<'help> {
     pub(crate) env: Option<(&'help OsStr, Option<OsString>)>,
     pub(crate) terminator: Option<&'help str>,
     pub(crate) index: Option<usize>,
-    pub(crate) help_heading: Option<&'help str>,
+    pub(crate) help_heading: Option<Option<&'help str>>,
     pub(crate) global: bool,
     pub(crate) exclusive: bool,
     pub(crate) value_hint: ValueHint,
@@ -156,7 +156,7 @@ impl<'help> Arg<'help> {
     /// Get the help heading specified for this argument, if any
     #[inline]
     pub fn get_help_heading(&self) -> Option<&str> {
-        self.help_heading
+        self.help_heading.unwrap_or_default()
     }
 
     /// Get the short option name for this argument, if any
@@ -4699,7 +4699,7 @@ impl<'help> Arg<'help> {
     where
         O: Into<Option<&'help str>>,
     {
-        self.help_heading = heading.into();
+        self.help_heading = Some(heading.into());
         self
     }
 

src/output/help.rs

@@ -755,7 +755,7 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
             .app
             .args
             .args()
-            .filter_map(|arg| arg.help_heading)
+            .filter_map(|arg| arg.get_help_heading())
             .collect::<IndexSet<_>>();
 
         let mut first = if !pos.is_empty() {
@@ -783,7 +783,7 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
                     .args
                     .args()
                     .filter(|a| {
-                        if let Some(help_heading) = a.help_heading {
+                        if let Some(help_heading) = a.get_help_heading() {
                             return help_heading == heading;
                         }
                         false

tests/help.rs

@@ -1788,14 +1788,17 @@ OPTIONS:
     -f, --fake <some>:<val>    some help
     -h, --help                 Print help information
     -s, --speed <SPEED>        How fast? [possible values: fast, slow]
+        --style <style>        Choose musical style to play the song
     -V, --version              Print version information
 
 NETWORKING:
     -a, --server-addr    Set server address
     -n, --no-proxy       Do not use system proxy settings
 
-SPECIAL:
+OVERRIDE SPECIAL:
     -b, --birthday-song <song>    Change which song is played for birthdays
+
+SPECIAL:
     -v, --birthday-song-volume <volume>    Change the volume of the birthday song
 ";
 
@@ -1822,15 +1825,17 @@ fn multiple_custom_help_headers() {
         .help_heading(Some("SPECIAL"))
         .arg(
             Arg::from("-b, --birthday-song <song> 'Change which song is played for birthdays'")
-                .help_heading(Some("IGNORE THIS")),
+                .help_heading(Some("OVERRIDE SPECIAL")),
         )
-        .help_heading(None)
         .arg(
-            Arg::from(
+            Arg::from("--style <style> 'Choose musical style to play the song'")
+                .required(false)
+                .help_heading(None),
+        )
+        .arg(Arg::from(
             "-v --birthday-song-volume <volume> 'Change the volume of the birthday song'",
-            )
+        ))
-            .help_heading(Some("SPECIAL")),
+        .help_heading(None)
-        )
         .arg(
             Arg::new("server-addr")
                 .short('a')
@@ -1869,8 +1874,10 @@ OPTIONS:
     -h, --help       Print help information
     -V, --version    Print version information
 
-SPECIAL:
+OVERRIDE SPECIAL:
     -b, --song <song>    Change which song is played for birthdays
+
+SPECIAL:
     -v, --song-volume <volume>    Change the volume of the birthday song
 ";
 
@@ -1891,13 +1898,12 @@ fn custom_help_headers_hidden_args() {
         .help_heading(Some("SPECIAL"))
         .arg(
             Arg::from("-b, --song <song> 'Change which song is played for birthdays'")
-                .help_heading(Some("IGNORE THIS")),
+                .help_heading(Some("OVERRIDE SPECIAL")),
         )
+        .arg(Arg::from(
+            "-v --song-volume <volume> 'Change the volume of the birthday song'",
+        ))
         .help_heading(None)
-        .arg(
-            Arg::from("-v --song-volume <volume> 'Change the volume of the birthday song'")
-                .help_heading(Some("SPECIAL")),
-        )
         .arg(
             Arg::new("server-addr")
                 .short('a')