diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..f0db20b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,82 @@
+# Collection of examples "how to use `structopt`"
+
+### [Help on the bottom](after_help.rs)
+
+How to append a postscript to the help message generated.
+
+### [At least N](at_least_two.rs)
+
+How to require presence of at least N values, like `val1 val2 ... valN ... valM`.
+
+### [Basic](basic.rs)
+
+A basic example how to use `structopt`.
+
+### [Deny missing docs](deny_missing_docs.rs)
+
+**This is not an example but a test**, it should be moved to `tests` folder
+as soon as [this](https://github.com/rust-lang/rust/issues/24584) is fixed (if ever).
+
+### [Doc comments](doc_comments.rs)
+
+How to use doc comments in place of `help/long_help`.
+
+### [Enums as arguments](enum_in_args.rs)
+
+How to use `arg_enum!` with `StructOpt`.
+
+### [Arguments of subcommands in separate `struct`](enum_tuple.rs)
+
+How to extract subcommands' args into external structs.
+
+### [Environment variables](env.rs)
+
+How to use environment variable fallback an how it interacts with `default_value`.
+
+### [Advanced](example.rs)
+
+Somewhat complex example of usage of `structopt`.
+
+### [Flatten](flatten.rs)
+
+How to use `#[structopt(flatten)]`
+
+### [`bash` completions](gen_completions.rs)
+
+Generating `bash` completions with `structopt`.
+
+### [Git](git.rs)
+
+Pseudo-`git` example, shows how to use subcommands and how to document them.
+
+### [Groups](group.rs)
+
+Using `clap::Arg::group` with `structopt`.
+
+### [`key=value` pairs](keyvalue.rs)
+
+How to parse `key=value` pairs.
+
+### [`--no-*` flags](negative_flag.rs)
+
+How to add `no-thing` flag which is `true` by default and `false` if passed.
+
+### [No version](no_version.rs)
+
+How to completely remove version.
+
+### [Rename all](rename_all.rs)
+
+How `#[structopt(rename_all)]` works.
+
+### [Skip](skip.rs)
+
+How to use `#[structopt(skip)]`.
+
+### [Aliases](subcommand_aliases.rs)
+
+How to use aliases
+
+### [`true` or `false`](true_or_false.rs)
+
+How to express "`"true"` or `"false"` argument.
diff --git a/examples/after_help.rs b/examples/after_help.rs
new file mode 100644
index 0000000..db2845f
--- /dev/null
+++ b/examples/after_help.rs
@@ -0,0 +1,19 @@
+//! How to append a postscript to the help message generated.
+
+use structopt::StructOpt;
+
+/// I am a program and I do things.
+///
+/// Sometimes they even work.
+#[derive(StructOpt, Debug)]
+#[structopt(after_help = "Beware `-d`, dragons be here")]
+struct Opt {
+    /// Release the dragon.
+    #[structopt(short)]
+    dragon: bool,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/at_least_two.rs b/examples/at_least_two.rs
new file mode 100644
index 0000000..683db50
--- /dev/null
+++ b/examples/at_least_two.rs
@@ -0,0 +1,15 @@
+//! How to require presence of at least N values,
+//! like `val1 val2 ... valN ... valM`.
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+struct Opt {
+    #[structopt(required = true, min_values = 2)]
+    foos: Vec<String>,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/basic.rs b/examples/basic.rs
new file mode 100644
index 0000000..510e0e0
--- /dev/null
+++ b/examples/basic.rs
@@ -0,0 +1,48 @@
+//! A somewhat comprehensive example of a typical `StructOpt` usage.use
+
+use std::path::PathBuf;
+use structopt::StructOpt;
+
+/// A basic example
+#[derive(StructOpt, Debug)]
+#[structopt(name = "basic")]
+struct Opt {
+    // A flag, true if used in the command line. Note doc comment will
+    // be used for the help message of the flag. The name of the
+    // argument will be, by default, based on the name of the field.
+    /// Activate debug mode
+    #[structopt(short, long)]
+    debug: bool,
+
+    // The number of occurrences of the `v/verbose` flag
+    /// Verbose mode (-v, -vv, -vvv, etc.)
+    #[structopt(short, long, parse(from_occurrences))]
+    verbose: u8,
+
+    /// Set speed
+    #[structopt(short, long, default_value = "42")]
+    speed: f64,
+
+    /// Output file
+    #[structopt(short, long, parse(from_os_str))]
+    output: PathBuf,
+
+    // the long option will be translated by default to kebab case,
+    // i.e. `--nb-cars`.
+    /// Number of cars
+    #[structopt(short = "c", long)]
+    nb_cars: Option<i32>,
+
+    /// admin_level to consider
+    #[structopt(short, long)]
+    level: Vec<String>,
+
+    /// Files to process
+    #[structopt(name = "FILE", parse(from_os_str))]
+    files: Vec<PathBuf>,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:#?}", opt);
+}
diff --git a/examples/deny_missing_docs.rs b/examples/deny_missing_docs.rs
new file mode 100644
index 0000000..82b1e63
--- /dev/null
+++ b/examples/deny_missing_docs.rs
@@ -0,0 +1,51 @@
+// 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.
+
+// This should be in tests but it will not work until
+// https://github.com/rust-lang/rust/issues/24584 is fixed
+
+//! A test to check that structopt compiles with deny(missing_docs)
+
+#![deny(missing_docs)]
+
+use structopt::StructOpt;
+
+/// The options
+#[derive(StructOpt, Debug, PartialEq)]
+pub struct Opt {
+    #[structopt(short)]
+    verbose: bool,
+    #[structopt(subcommand)]
+    cmd: Option<Cmd>,
+}
+
+/// Some subcommands
+#[derive(StructOpt, Debug, PartialEq)]
+pub enum Cmd {
+    /// command A
+    A,
+    /// command B
+    B {
+        /// Alice?
+        #[structopt(short)]
+        alice: bool,
+    },
+    /// command C
+    C(COpt),
+}
+
+/// The options for C
+#[derive(StructOpt, Debug, PartialEq)]
+pub struct COpt {
+    #[structopt(short)]
+    bob: bool,
+}
+
+fn main() {
+    println!("{:?}", Opt::from_args());
+}
diff --git a/examples/doc_comments.rs b/examples/doc_comments.rs
new file mode 100644
index 0000000..810101f
--- /dev/null
+++ b/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);
+}
diff --git a/examples/enum_in_args.rs b/examples/enum_in_args.rs
new file mode 100644
index 0000000..70347da
--- /dev/null
+++ b/examples/enum_in_args.rs
@@ -0,0 +1,25 @@
+//! How to use `arg_enum!` with `StructOpt`.
+
+use clap::arg_enum;
+use structopt::StructOpt;
+
+arg_enum! {
+    #[derive(Debug)]
+    enum Baz {
+        Foo,
+        Bar,
+        FooBar
+    }
+}
+
+#[derive(StructOpt, Debug)]
+struct Opt {
+    /// Important argument.
+    #[structopt(possible_values = &Baz::variants(), case_insensitive = true)]
+    i: Baz,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/enum_tuple.rs b/examples/enum_tuple.rs
new file mode 100644
index 0000000..0bad2e6
--- /dev/null
+++ b/examples/enum_tuple.rs
@@ -0,0 +1,26 @@
+//! How to extract subcommands' args into external structs.
+
+use structopt::StructOpt;
+
+#[derive(Debug, StructOpt)]
+pub struct Foo {
+    pub bar: Option<String>,
+}
+
+#[derive(Debug, StructOpt)]
+pub enum Command {
+    #[structopt(name = "foo")]
+    Foo(Foo),
+}
+
+#[derive(Debug, StructOpt)]
+#[structopt(name = "classify")]
+pub struct ApplicationArguments {
+    #[structopt(subcommand)]
+    pub command: Command,
+}
+
+fn main() {
+    let opt = ApplicationArguments::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/env.rs b/examples/env.rs
new file mode 100644
index 0000000..0477089
--- /dev/null
+++ b/examples/env.rs
@@ -0,0 +1,26 @@
+//! How to use environment variable fallback an how it
+//! interacts with `default_value`.
+
+use structopt::StructOpt;
+
+/// Example for allowing to specify options via environment variables.
+#[derive(StructOpt, Debug)]
+#[structopt(name = "env")]
+struct Opt {
+    // Use `env` to enable specifying the option with an environment
+    // variable. Command line arguments take precedence over env.
+    /// URL for the API server
+    #[structopt(long, env = "API_URL")]
+    api_url: String,
+
+    // The default value is used if neither argument nor environment
+    // variable is specified.
+    /// Number of retries
+    #[structopt(long, env = "RETRIES", default_value = "5")]
+    retries: u32,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:#?}", opt);
+}
diff --git a/examples/example.rs b/examples/example.rs
new file mode 100644
index 0000000..7a9a514
--- /dev/null
+++ b/examples/example.rs
@@ -0,0 +1,54 @@
+//! Somewhat complex example of usage of structopt.
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+#[structopt(name = "example")]
+/// An example of StructOpt usage.
+struct Opt {
+    // A flag, true if used in the command line.
+    #[structopt(short, long)]
+    /// Activate debug mode
+    debug: bool,
+
+    // An argument of type float, with a default value.
+    #[structopt(short, long, default_value = "42")]
+    /// Set speed
+    speed: f64,
+
+    // Needed parameter, the first on the command line.
+    /// Input file
+    input: String,
+
+    // An optional parameter, will be `None` if not present on the
+    // command line.
+    /// Output file, stdout if not present
+    output: Option<String>,
+
+    // An optional parameter with optional value, will be `None` if
+    // not present on the command line, will be `Some(None)` if no
+    // argument is provided (i.e. `--log`) and will be
+    // `Some(Some(String))` if argument is provided (e.g. `--log
+    // log.txt`).
+    #[structopt(long)]
+    #[allow(clippy::option_option)]
+    /// Log file, stdout if no file, no logging if not present
+    log: Option<Option<String>>,
+
+    // An optional list of values, will be `None` if not present on
+    // the command line, will be `Some(vec![])` if no argument is
+    // provided (i.e. `--optv`) and will be `Some(Some(String))` if
+    // argument list is provided (e.g. `--optv a b c`).
+    #[structopt(long)]
+    optv: Option<Vec<String>>,
+
+    // Skipped option: it won't be parsed and will be filled with the
+    // default value for its type (in this case it'll be an empty string).
+    #[structopt(skip)]
+    skipped: String,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/flatten.rs b/examples/flatten.rs
new file mode 100644
index 0000000..d51647f
--- /dev/null
+++ b/examples/flatten.rs
@@ -0,0 +1,29 @@
+//! How to use flattening.
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+struct Cmdline {
+    /// switch verbosity on
+    #[structopt(short)]
+    verbose: bool,
+
+    #[structopt(flatten)]
+    daemon_opts: DaemonOpts,
+}
+
+#[derive(StructOpt, Debug)]
+struct DaemonOpts {
+    /// daemon user
+    #[structopt(short)]
+    user: String,
+
+    /// daemon group
+    #[structopt(short)]
+    group: String,
+}
+
+fn main() {
+    let opt = Cmdline::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/gen_completions.rs b/examples/gen_completions.rs
new file mode 100644
index 0000000..4f35b07
--- /dev/null
+++ b/examples/gen_completions.rs
@@ -0,0 +1,26 @@
+// Copyright 2019-present structopt developers
+//
+// 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::clap::Shell;
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+/// An example of how to generate bash completions with structopt.
+struct Opt {
+    #[structopt(short, long)]
+    /// Activate debug mode
+    debug: bool,
+}
+
+fn main() {
+    // generate `bash` completions in "target" directory
+    Opt::clap().gen_completions(env!("CARGO_PKG_NAME"), Shell::Bash, "target");
+
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/git.rs b/examples/git.rs
new file mode 100644
index 0000000..494e9d1
--- /dev/null
+++ b/examples/git.rs
@@ -0,0 +1,35 @@
+//! `git.rs` serves as a demonstration of how to use subcommands,
+//! as well as a demonstration of adding documentation to subcommands.
+//! Documentation can be added either through doc comments or
+//! `help`/`about` attributes.
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+#[structopt(name = "git")]
+/// the stupid content tracker
+enum Opt {
+    /// fetch branches from remote repository
+    Fetch {
+        #[structopt(long)]
+        dry_run: bool,
+        #[structopt(long)]
+        all: bool,
+        #[structopt(default_value = "origin")]
+        repository: String,
+    },
+    #[structopt(help = "add files to the staging area")]
+    Add {
+        #[structopt(short)]
+        interactive: bool,
+        #[structopt(short)]
+        all: bool,
+        files: Vec<String>,
+    },
+}
+
+fn main() {
+    let matches = Opt::from_args();
+
+    println!("{:?}", matches);
+}
diff --git a/examples/group.rs b/examples/group.rs
new file mode 100644
index 0000000..d53de6a
--- /dev/null
+++ b/examples/group.rs
@@ -0,0 +1,31 @@
+//! How to use `clap::Arg::group`
+
+use structopt::{clap::ArgGroup, StructOpt};
+
+#[derive(StructOpt, Debug)]
+#[structopt(group = ArgGroup::with_name("verb").required(true))]
+struct Opt {
+    /// Set a custom HTTP verb
+    #[structopt(long, group = "verb")]
+    method: Option<String>,
+    /// HTTP GET
+    #[structopt(long, group = "verb")]
+    get: bool,
+    /// HTTP HEAD
+    #[structopt(long, group = "verb")]
+    head: bool,
+    /// HTTP POST
+    #[structopt(long, group = "verb")]
+    post: bool,
+    /// HTTP PUT
+    #[structopt(long, group = "verb")]
+    put: bool,
+    /// HTTP DELETE
+    #[structopt(long, group = "verb")]
+    delete: bool,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/keyvalue.rs b/examples/keyvalue.rs
new file mode 100644
index 0000000..12ce6fc
--- /dev/null
+++ b/examples/keyvalue.rs
@@ -0,0 +1,36 @@
+//! How to parse "key=value" pairs with structopt.
+
+use std::error::Error;
+use structopt::StructOpt;
+
+/// Parse a single key-value pair
+fn parse_key_val<T, U>(s: &str) -> Result<(T, U), Box<dyn Error>>
+where
+    T: std::str::FromStr,
+    T::Err: Error + 'static,
+    U: std::str::FromStr,
+    U::Err: Error + 'static,
+{
+    let pos = s
+        .find('=')
+        .ok_or_else(|| format!("invalid KEY=value: no `=` found in `{}`", s))?;
+    Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
+}
+
+#[derive(StructOpt, Debug)]
+struct Opt {
+    // number_of_values = 1 forces the user to repeat the -D option for each key-value pair:
+    // my_program -D a=1 -D b=2
+    // Without number_of_values = 1 you can do:
+    // my_program -D a=1 b=2
+    // but this makes adding an argument after the values impossible:
+    // my_program -D a=1 -D b=2 my_input_file
+    // becomes invalid.
+    #[structopt(short = "D", parse(try_from_str = parse_key_val), number_of_values = 1)]
+    defines: Vec<(String, i32)>,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/negative_flag.rs b/examples/negative_flag.rs
new file mode 100644
index 0000000..b178bf5
--- /dev/null
+++ b/examples/negative_flag.rs
@@ -0,0 +1,15 @@
+//! How to add `no-thing` flag which is `true` by default and
+//! `false` if passed.
+
+use structopt::StructOpt;
+
+#[derive(Debug, StructOpt)]
+struct Opt {
+    #[structopt(long = "no-verbose", parse(from_flag = std::ops::Not::not))]
+    verbose: bool,
+}
+
+fn main() {
+    let cmd = Opt::from_args();
+    println!("{:#?}", cmd);
+}
diff --git a/examples/no_version.rs b/examples/no_version.rs
new file mode 100644
index 0000000..a542ec1
--- /dev/null
+++ b/examples/no_version.rs
@@ -0,0 +1,17 @@
+//! How to completely remove version.
+
+use structopt::clap::AppSettings;
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+#[structopt(
+    name = "no_version",
+    no_version,
+    global_settings = &[AppSettings::DisableVersion]
+)]
+struct Opt {}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/rename_all.rs b/examples/rename_all.rs
new file mode 100644
index 0000000..35f3c4f
--- /dev/null
+++ b/examples/rename_all.rs
@@ -0,0 +1,74 @@
+//! Example on how the `rename_all` parameter works.
+//!
+//! `rename_all` can be used to override the casing style used during argument
+//! generation. By default the `kebab-case` style will be used but there are a wide
+//! variety of other styles available.
+//!
+//! ## Supported styles overview:
+//!
+//! - **Camel Case**: Indicate word boundaries with uppercase letter, excluding
+//!                   the first word.
+//! - **Kebab Case**: Keep all letters lowercase and indicate word boundaries
+//!                   with hyphens.
+//! - **Pascal Case**: Indicate word boundaries with uppercase letter,
+//!                    including the first word.
+//! - **Screaming Snake Case**: Keep all letters uppercase and indicate word
+//!                             boundaries with underscores.
+//! - **Snake Case**: Keep all letters lowercase and indicate word boundaries
+//!                   with underscores.
+//! - **Verbatim**: Use the original attribute name defined in the code.
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+#[structopt(name = "rename_all", rename_all = "screaming_snake_case")]
+enum Opt {
+    // This subcommand will be named `FIRST_COMMAND`. As the command doesn't
+    // override the initial casing style, ...
+    /// A screaming loud first command. Only use if necessary.
+    FirstCommand {
+        // this flag will be available as `--FOO` and `-F`.
+        /// This flag will even scream louder.
+        #[structopt(long, short)]
+        foo: bool,
+    },
+
+    // As we override the casing style for this variant the related subcommand
+    // will be named `SecondCommand`.
+    /// Not nearly as loud as the first command.
+    #[structopt(rename_all = "pascal_case")]
+    SecondCommand {
+        // We can also override it again on a single field.
+        /// Nice quiet flag. No one is annoyed.
+        #[structopt(rename_all = "snake_case", long)]
+        bar_option: bool,
+
+        // Renaming will not be propagated into subcommand flagged enums. If
+        // a non default casing style is required it must be defined on the
+        // enum itself.
+        #[structopt(subcommand)]
+        cmds: Subcommands,
+
+        // or flattened structs.
+        #[structopt(flatten)]
+        options: BonusOptions,
+    },
+}
+
+#[derive(StructOpt, Debug)]
+enum Subcommands {
+    // This one will be available as `first-subcommand`.
+    FirstSubcommand,
+}
+
+#[derive(StructOpt, Debug)]
+struct BonusOptions {
+    // And this one will be available as `baz-option`.
+    #[structopt(long)]
+    baz_option: bool,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/skip.rs b/examples/skip.rs
new file mode 100644
index 0000000..1f44769
--- /dev/null
+++ b/examples/skip.rs
@@ -0,0 +1,47 @@
+//! How to use `#[structopt(skip)]`
+
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug, PartialEq)]
+pub struct Opt {
+    #[structopt(long, short)]
+    number: u32,
+    #[structopt(skip)]
+    k: Kind,
+    #[structopt(skip)]
+    v: Vec<u32>,
+
+    #[structopt(skip = Kind::A)]
+    k2: Kind,
+    #[structopt(skip = vec![1, 2, 3])]
+    v2: Vec<u32>,
+    #[structopt(skip = "cake")] // &str implements Into<String>
+    s: String,
+}
+
+#[derive(Debug, PartialEq)]
+enum Kind {
+    A,
+    B,
+}
+
+impl Default for Kind {
+    fn default() -> Self {
+        return Kind::B;
+    }
+}
+
+fn main() {
+    assert_eq!(
+        Opt::from_iter(&["test", "-n", "10"]),
+        Opt {
+            number: 10,
+            k: Kind::B,
+            v: vec![],
+
+            k2: Kind::A,
+            v2: vec![1, 2, 3],
+            s: String::from("cake")
+        }
+    );
+}
diff --git a/examples/subcommand_aliases.rs b/examples/subcommand_aliases.rs
new file mode 100644
index 0000000..30b8cc3
--- /dev/null
+++ b/examples/subcommand_aliases.rs
@@ -0,0 +1,21 @@
+//! How to assign some aliases to subcommands
+
+use structopt::clap::AppSettings;
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug)]
+// https://docs.rs/clap/2/clap/enum.AppSettings.html#variant.InferSubcommands
+#[structopt(setting = AppSettings::InferSubcommands)]
+enum Opt {
+    // https://docs.rs/clap/2/clap/struct.App.html#method.alias
+    #[structopt(alias = "foobar")]
+    Foo,
+    // https://docs.rs/clap/2/clap/struct.App.html#method.aliases
+    #[structopt(aliases = &["baz", "fizz"])]
+    Bar,
+}
+
+fn main() {
+    let opt = Opt::from_args();
+    println!("{:?}", opt);
+}
diff --git a/examples/true_or_false.rs b/examples/true_or_false.rs
new file mode 100644
index 0000000..31a543e
--- /dev/null
+++ b/examples/true_or_false.rs
@@ -0,0 +1,41 @@
+//! How to parse `--foo=true --bar=false` and turn them into bool.
+
+use structopt::StructOpt;
+
+fn true_or_false(s: &str) -> Result<bool, &'static str> {
+    match s {
+        "true" => Ok(true),
+        "false" => Ok(false),
+        _ => Err("expected `true` or `false`"),
+    }
+}
+
+#[derive(StructOpt, Debug, PartialEq)]
+struct Opt {
+    // Default parser for `try_from_str` is FromStr::from_str.
+    // `impl FromStr for bool` parses `true` or `false` so this
+    // works as expected.
+    #[structopt(long, parse(try_from_str))]
+    foo: bool,
+
+    // Of course, this could be done with an explicit parser function.
+    #[structopt(long, parse(try_from_str = true_or_false))]
+    bar: bool,
+
+    // `bool` can be positional only with explicit `parse(...)` annotation
+    #[structopt(long, parse(try_from_str))]
+    boom: bool,
+}
+
+fn main() {
+    assert_eq!(
+        Opt::from_iter(&["test", "--foo=true", "--bar=false", "true"]),
+        Opt {
+            foo: true,
+            bar: false,
+            boom: true
+        }
+    );
+    // no beauty, only truth and falseness
+    assert!(Opt::from_iter_safe(&["test", "--foo=beauty"]).is_err());
+}