Merge pull request #4340 from epage/doc-comment

fix(derive): Apply doc comments for `#[command(subcommand)]`

clap_derive/src/item.rs

@@ -143,7 +143,7 @@ impl Item {
         let parsed_attrs = ClapAttr::parse_all(&variant.attrs);
         res.infer_kind(&parsed_attrs);
         res.push_attrs(&parsed_attrs);
-        if matches!(&*res.kind, Kind::Command(_)) {
+        if matches!(&*res.kind, Kind::Command(_) | Kind::Subcommand(_)) {
             res.push_doc_comment(&variant.attrs, "about", true);
         }
 
@@ -155,6 +155,9 @@ impl Item {
                         "methods are not allowed for flattened entry"
                     );
                 }
+
+                // ignore doc comments
+                res.doc_comment = vec![];
             }
 
             Kind::Subcommand(_)
@@ -228,6 +231,9 @@ impl Item {
                         "methods are not allowed for flattened entry"
                     );
                 }
+
+                // ignore doc comments
+                res.doc_comment = vec![];
             }
 
             Kind::Subcommand(_) => {

tests/derive/doc_comments_help.rs

@@ -14,7 +14,7 @@
 
 use crate::utils;
 
-use clap::{CommandFactory, Parser, ValueEnum};
+use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
 
 #[test]
 fn doc_comments() {
@@ -248,3 +248,31 @@ fn doc_comment_about_handles_both_abouts() {
     // comment.
     assert_eq!(cmd.get_long_about(), None);
 }
+
+#[test]
+fn respect_subcommand_doc_comment() {
+    #[derive(Parser, Debug)]
+    pub enum Cmd {
+        /// For child
+        #[command(subcommand)]
+        Child(Child),
+    }
+
+    #[derive(Subcommand, Debug)]
+    pub enum Child {
+        One,
+        Twp,
+    }
+
+    const OUTPUT: &str = "\
+Usage: cmd <COMMAND>
+
+Commands:
+  child  For child
+  help   Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help  Print help information
+";
+    utils::assert_output::<Cmd>("cmd --help", OUTPUT, false);
+}