1 files changed, 74 insertions, 0 deletions
diff --git a/structopt/examples/doc_comments.rs b/structopt/examples/doc_comments.rs
new file mode 100644
index 0000000..810101f
--- /dev/null
+++ b/structopt/examples/doc_comments.rs
@@ -0,0 +1,74 @@
+//! How to use doc comments in place of `help/long_help`.
+
+use structopt::StructOpt;
+
+/// A basic example for the usage of doc comments as replacement
+/// of the arguments `help`, `long_help`, `about` and `long_about`.
+#[derive(StructOpt, Debug)]
+#[structopt(name = "basic")]
+struct Opt {
+    /// Just use doc comments to replace `help`, `long_help`,
+    /// `about` or `long_about` input.
+    #[structopt(short, long)]
+    first_flag: bool,
+
+    /// Split between `help` and `long_help`.
+    ///
+    /// In the previous case structopt is going to present
+    /// the whole comment both as text for the `help` and the
+    /// `long_help` argument.
+    ///
+    /// But if the doc comment is formatted like this example
+    /// -- with an empty second line splitting the heading and
+    /// the rest of the comment -- only the first line is used
+    /// as `help` argument. The `long_help` argument will still
+    /// contain the whole comment.
+    ///
+    /// ## Attention
+    ///
+    /// Any formatting next to empty lines that could be used
+    /// inside a doc comment is currently not preserved. If
+    /// lists or other well formatted content is required it is
+    /// necessary to use the related structopt argument with a
+    /// raw string as shown on the `third_flag` description.
+    #[structopt(short, long)]
+    second_flag: bool,
+
+    #[structopt(
+        short,
+        long,
+        long_help = r"This is a raw string.
+
+It can be used to pass well formatted content (e.g. lists or source
+code) in the description:
+
+ - first example list entry
+ - second example list entry
+ "
+    )]
+    third_flag: bool,
+
+    #[structopt(subcommand)]
+    sub_command: SubCommand,
+}
+
+#[derive(StructOpt, Debug)]
+#[structopt()]
+enum SubCommand {
+    /// The same rules described previously for flags. Are
+    /// also true for in regards of sub-commands.
+    First,
+
+    /// Applicable for both `about` an `help`.
+    ///
+    /// The formatting rules described in the comment of the
+    /// `second_flag` also apply to the description of
+    /// sub-commands which is normally given through the `about`
+    /// and `long_about` arguments.
+    Second,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}