Merge #2952 #2953

2952: fix(derive): Don't duplicate subcommand aliases r=pksunkara a=epage



2953: docs(app): Correlate help_heading and subcommand_placeholder r=pksunkara a=epage



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

clap_derive/src/derives/subcommand.rs

@@ -240,14 +240,24 @@ fn gen_augment(
 
                 _ => {
                     let subcommand_var = Ident::new("__clap_subcommand", Span::call_site());
-                    let arg_block = match variant.fields {
+                    let sub_augment = match variant.fields {
                         Named(ref fields) => {
+                            // Defer to `gen_augment` for adding app methods
                             args::gen_augment(&fields.named, &subcommand_var, &attrs, override_required)
                         }
-                        Unit => quote!( #subcommand_var ),
+                        Unit => {
+                            let arg_block = quote!( #subcommand_var );
+                            let initial_app_methods = attrs.initial_top_level_methods();
+                            let final_from_attrs = attrs.final_top_level_methods();
+                            quote! {
+                                let #subcommand_var = #subcommand_var #initial_app_methods;
+                                let #subcommand_var = #arg_block;
+                                #subcommand_var #final_from_attrs
+                            }
+                        },
                         Unnamed(FieldsUnnamed { ref unnamed, .. }) if unnamed.len() == 1 => {
                             let ty = &unnamed[0];
-                            if override_required {
+                            let arg_block = if override_required {
                                 quote_spanned! { ty.span()=>
                                     {
                                         <#ty as clap::Args>::augment_args_for_update(#subcommand_var)
@@ -259,6 +269,13 @@ fn gen_augment(
                                         <#ty as clap::Args>::augment_args(#subcommand_var)
                                     }
                                 }
+                            };
+                            let initial_app_methods = attrs.initial_top_level_methods();
+                            let final_from_attrs = attrs.final_top_level_methods();
+                            quote! {
+                                let #subcommand_var = #subcommand_var #initial_app_methods;
+                                let #subcommand_var = #arg_block;
+                                #subcommand_var #final_from_attrs
                             }
                         }
                         Unnamed(..) => {
@@ -267,14 +284,10 @@ fn gen_augment(
                     };
 
                     let name = attrs.cased_name();
-                    let initial_app_methods = attrs.initial_top_level_methods();
-                    let final_from_attrs = attrs.final_top_level_methods();
                     let subcommand = quote! {
                         let #app_var = #app_var.subcommand({
                             let #subcommand_var = clap::App::new(#name);
-                            let #subcommand_var = #subcommand_var #initial_app_methods;
-                            let #subcommand_var = #arg_block;
-                            #subcommand_var #final_from_attrs
+                            #sub_augment
                         });
                     };
                     Some(subcommand)

clap_derive/tests/issues.rs

@@ -75,6 +75,32 @@ fn issue_324() {
     assert!(help.contains("MY_VERSION"));
 }
 
+#[test]
+fn issue_418() {
+    #[derive(Debug, Parser)]
+    struct Opts {
+        #[clap(subcommand)]
+        /// The command to run
+        command: Command,
+    }
+
+    #[derive(Debug, Subcommand)]
+    enum Command {
+        /// Reticulate the splines
+        #[clap(visible_alias = "ret")]
+        Reticulate {
+            /// How many splines
+            num_splines: u8,
+        },
+        /// Frobnicate the rest
+        #[clap(visible_alias = "frob")]
+        Frobnicate,
+    }
+
+    let help = get_long_help::<Opts>();
+    assert!(help.contains("Reticulate the splines [aliases: ret]"));
+}
+
 #[test]
 fn issue_490() {
     use clap::Parser;

src/build/app/mod.rs

@@ -97,7 +97,7 @@ pub struct App<'help> {
     pub(crate) groups: Vec<ArgGroup<'help>>,
     pub(crate) current_help_heading: Option<&'help str>,
     pub(crate) subcommand_placeholder: Option<&'help str>,
-    pub(crate) subcommand_header: Option<&'help str>,
+    pub(crate) subcommand_heading: Option<&'help str>,
 }
 
 impl<'help> App<'help> {
@@ -1129,6 +1129,8 @@ impl<'help> App<'help> {
     /// This is useful if the default `OPTIONS` or `ARGS` headings are
     /// not specific enough for one's use case.
     ///
+    /// For subcommands, see [`App::subcommand_placeholder`]
+    ///
     /// [`App::arg`]: App::arg()
     /// [`Arg::help_heading`]: crate::Arg::help_heading()
     #[inline]
@@ -2292,7 +2294,7 @@ impl<'help> App<'help> {
     }
 
     /// Sets the placeholder text used for subcommands when printing usage and help.
-    /// By default, this is "SUBCOMMAND" with a header of "SUBCOMMANDS".
+    /// By default, this is "SUBCOMMAND" with a heading of "SUBCOMMANDS".
     ///
     /// # Examples
     ///
@@ -2348,13 +2350,13 @@ impl<'help> App<'help> {
     ///     help    Print this message or the help of the given subcommand(s)
     ///     sub1
     /// ```
-    pub fn subcommand_placeholder<S, T>(mut self, placeholder: S, header: T) -> Self
+    pub fn subcommand_placeholder<S, T>(mut self, placeholder: S, heading: T) -> Self
     where
         S: Into<&'help str>,
         T: Into<&'help str>,
     {
         self.subcommand_placeholder = Some(placeholder.into());
-        self.subcommand_header = Some(header.into());
+        self.subcommand_heading = Some(heading.into());
         self
     }
 }

src/output/help.rs

@@ -812,7 +812,7 @@ impl<'help, 'app, 'parser, 'writer> Help<'help, 'app, 'parser, 'writer> {
                 self.none("\n\n")?;
             }
 
-            self.warning(self.parser.app.subcommand_header.unwrap_or("SUBCOMMANDS"))?;
+            self.warning(self.parser.app.subcommand_heading.unwrap_or("SUBCOMMANDS"))?;
             self.warning(":\n")?;
 
             self.write_subcommands(self.parser.app)?;