Repository: TeXitoi/structopt (Rust)

Issue:
Documenting flattened fields?
I'm trying to write Cargo documentation for a field that is flattened by structopt. This seems to be rejected as a compile-time error, via:

```
error: proc-macro derive panicked
  --> foo/src/serve.rs:12:10
   |
12 | #[derive(StructOpt, Debug)]
   |          ^^^^^^^^^
   |
   = help: message: methods and doc comments are not allowed for flattened entry

error: aborting due to previous error
```

I imagine StructOpt chose this behavior for automatically generated `--help`, however this directly conflicts with clippy lints that require documentation. Ie, i can't merge this structopt code as it either fails clippy lints or fails to compile due to StructOpt.

Is there a way to disable this compilation failure? Ie, ignore the flattened field's documentation? Maybe something like a `structopt(flatten, ignore_documentation)` attribute?


Discussion:
I think we can just ignore the doc comments on top of `#[flatten/subcommand]` fields.



Patch:
diff --git a/structopt-derive/src/attrs.rs b/structopt-derive/src/attrs.rs
index d75b50ca..a0ae2b77 100644
--- a/structopt-derive/src/attrs.rs
+++ b/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 => {}


Test patch:
diff --git a/tests/flatten.rs b/tests/flatten.rs
index ddc0ef7b..05de1856 100644
--- a/tests/flatten.rs
+++ b/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"));
+}
diff --git a/tests/ui/flatten_and_doc.rs b/tests/ui/flatten_and_doc.rs
deleted file mode 100644
index 2dc154d7..00000000
--- a/tests/ui/flatten_and_doc.rs
+++ /dev/null
@@ -1,30 +0,0 @@
-// Copyright 2018 Guillaume Pinot (@TeXitoi) <texitoi@texitoi.eu>
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
-use structopt::StructOpt;
-
-#[derive(StructOpt, Debug)]
-struct DaemonOpts {
-    #[structopt(short)]
-    user: String,
-    #[structopt(short)]
-    group: String,
-}
-
-#[derive(StructOpt, Debug)]
-#[structopt(name = "basic")]
-struct Opt {
-    /// Opts.
-    #[structopt(flatten)]
-    opts: DaemonOpts,
-}
-
-fn main() {
-    let opt = Opt::from_args();
-    println!("{:?}", opt);
-}
diff --git a/tests/ui/flatten_and_doc.stderr b/tests/ui/flatten_and_doc.stderr
deleted file mode 100644
index 2724dbbb..00000000
--- a/tests/ui/flatten_and_doc.stderr
+++ /dev/null
@@ -1,5 +0,0 @@
-error: methods and doc comments are not allowed for flattened entry
-  --> $DIR/flatten_and_doc.rs:23:17
-   |
-23 |     #[structopt(flatten)]
-   |                 ^^^^^^^
diff --git a/tests/ui/flatten_and_methods.stderr b/tests/ui/flatten_and_methods.stderr
index f058eb3f..77d97ae3 100644
--- a/tests/ui/flatten_and_methods.stderr
+++ b/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)]