Allow #[flatten] fields to have doc comments but ignore them (comments)

structopt-derive/src/attrs.rs

@@ -437,12 +437,16 @@ impl Attrs {
                         "parse attribute is not allowed for flattened entry"
                     );
                 }
-                if res.has_explicit_methods() || res.has_doc_methods() {
+                if res.has_explicit_methods() {
                     abort!(
                         res.kind.span(),
-                        "methods and doc comments are not allowed for flattened entry"
+                        "methods are not allowed for flattened entry"
                     );
                 }
+
+                if res.has_doc_methods() {
+                    res.doc_comment = vec![];
+                }
             }
 
             Kind::ExternalSubcommand => {}

tests/flatten.rs

@@ -8,6 +8,8 @@
 
 use structopt::StructOpt;
 
+mod utils;
+
 #[test]
 fn flatten() {
     #[derive(StructOpt, PartialEq, Debug)]
@@ -151,3 +153,30 @@ fn subcommand_in_flatten() {
 
     Struct1::from_iter(&["test", "command", "foo"]);
 }
+
+#[test]
+fn flatten_doc_comment() {
+    #[derive(StructOpt, PartialEq, Debug)]
+    struct Common {
+        /// This is an arg. Arg means "argument". Command line argument.
+        arg: i32,
+    }
+
+    #[derive(StructOpt, PartialEq, Debug)]
+    struct Opt {
+        /// The very important comment that clippy had me put here.
+        /// It knows better.
+        #[structopt(flatten)]
+        common: Common,
+    }
+    assert_eq!(
+        Opt {
+            common: Common { arg: 42 }
+        },
+        Opt::from_iter(&["test", "42"])
+    );
+
+    let help = utils::get_help::<Opt>();
+    assert!(help.contains("This is an arg."));
+    assert!(!help.contains("The very important"));
+}

tests/ui/flatten_and_methods.stderr

@@ -1,4 +1,4 @@
-error: methods and doc comments are not allowed for flattened entry
+error: methods are not allowed for flattened entry
   --> $DIR/flatten_and_methods.rs:22:24
    |
 22 |     #[structopt(short, flatten)]