diff --git a/.cargo_vcs_info.json b/.cargo_vcs_info.json
index 0057313..f72fb65 100644
--- a/.cargo_vcs_info.json
+++ b/.cargo_vcs_info.json
@@ -1,5 +1,6 @@
 {
   "git": {
-    "sha1": "88e5402df017c052f1524f293b2e13bd01810819"
-  }
-}
+    "sha1": "97e92a3755a65f8ea44c994fd403208e7d97f561"
+  },
+  "path_in_vcs": ""
+}
\ No newline at end of file
diff --git a/Android.bp b/Android.bp
index ff4330f..36e6af0 100644
--- a/Android.bp
+++ b/Android.bp
@@ -42,7 +42,7 @@
     host_supported: true,
     crate_name: "structopt",
     cargo_env_compat: true,
-    cargo_pkg_version: "0.3.23",
+    cargo_pkg_version: "0.3.26",
     srcs: ["src/lib.rs"],
     edition: "2018",
     features: ["default"],
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cdf1ba7..30353f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,11 @@
+# v0.3.25 (2021-10-18)
+
+* Fix duplication of aliases in subcommands [#504](https://github.com/TeXitoi/structopt/pull/504)
+
+# v0.3.25 (2021-10-18)
+
+* No changes
+
 # v0.3.23 (2021-08-30)
 
 * Update minimal rust version to 1.46 because of bitflags 1.3
diff --git a/Cargo.toml b/Cargo.toml
index ba91744..321b31e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,17 +3,16 @@
 # When uploading crates to the registry Cargo will automatically
 # "normalize" Cargo.toml files for maximal compatibility
 # with all versions of Cargo and also rewrite `path` dependencies
-# to registry (e.g., crates.io) dependencies
+# to registry (e.g., crates.io) dependencies.
 #
-# If you believe there's an error in this file please file an
-# issue against the rust-lang/cargo repository. If you're
-# editing this file be aware that the upstream Cargo.toml
-# will likely look very different (and much more reasonable)
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
 
 [package]
 edition = "2018"
 name = "structopt"
-version = "0.3.23"
+version = "0.3.26"
 authors = ["Guillaume Pinot <texitoi@texitoi.eu>", "others"]
 description = "Parse command line argument by defining a struct."
 documentation = "https://docs.rs/structopt"
@@ -35,7 +34,7 @@
 package = "paw"
 
 [dependencies.structopt-derive]
-version = "=0.4.16"
+version = "=0.4.18"
 [dev-dependencies.rustversion]
 version = "1"
 
diff --git a/Cargo.toml.orig b/Cargo.toml.orig
index bccc07f..fb77ef2 100644
--- a/Cargo.toml.orig
+++ b/Cargo.toml.orig
@@ -1,6 +1,6 @@
 [package]
 name = "structopt"
-version = "0.3.23"
+version = "0.3.26"
 edition = "2018"
 authors = ["Guillaume Pinot <texitoi@texitoi.eu>", "others"]
 description = "Parse command line argument by defining a struct."
@@ -28,7 +28,7 @@
 
 [dependencies]
 clap = { version = "2.33", default-features = false }
-structopt-derive = { path = "structopt-derive", version = "=0.4.16" }
+structopt-derive = { path = "structopt-derive", version = "=0.4.18" }
 lazy_static = "1.4.0"
 paw_dep = { version = "1", optional = true, package = "paw" }
 
diff --git a/METADATA b/METADATA
index 4f3ccd1..4839f47 100644
--- a/METADATA
+++ b/METADATA
@@ -7,13 +7,13 @@
   }
   url {
     type: ARCHIVE
-    value: "https://static.crates.io/crates/structopt/structopt-0.3.23.crate"
+    value: "https://static.crates.io/crates/structopt/structopt-0.3.26.crate"
   }
-  version: "0.3.23"
+  version: "0.3.26"
   license_type: NOTICE
   last_upgrade_date {
-    year: 2021
-    month: 9
-    day: 22
+    year: 2022
+    month: 3
+    day: 1
   }
 }
diff --git a/README.md b/README.md
index dfb2059..bff1587 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,12 @@
 
 Parse command line arguments by defining a struct.  It combines [clap](https://crates.io/crates/clap) with custom derive.
 
+## Maintenance
+
+As clap v3 is now out, and the structopt features are integrated into (almost as-is), structopt is now in maintenance mode: no new feature will be added.
+
+Bugs will be fixed, and documentation improvements will be accepted.
+
 ## Documentation
 
 Find it on [Docs.rs](https://docs.rs/structopt).  You can also check the [examples](https://github.com/TeXitoi/structopt/tree/master/examples) and the [changelog](https://github.com/TeXitoi/structopt/blob/master/CHANGELOG.md).
diff --git a/examples/README.md b/examples/README.md
index b485393..1475e2a 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -31,7 +31,7 @@
 
 ### [Environment variables](env.rs)
 
-How to use environment variable fallback an how it interacts with `default_value`.
+How to use environment variable fallback and how it interacts with `default_value`.
 
 ### [Advanced](example.rs)
 
diff --git a/examples/after_help.rs b/examples/after_help.rs
index db2845f..75816c7 100644
--- a/examples/after_help.rs
+++ b/examples/after_help.rs
@@ -1,4 +1,28 @@
 //! How to append a postscript to the help message generated.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//! I am a program and I do things.
+//!
+//! Sometimes they even work.
+//!
+//! USAGE:
+//!     after_help [FLAGS]
+//!
+//! FLAGS:
+//!     -d
+//!             Release the dragon
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -V, --version
+//!             Prints version information
+//!
+//!
+//! Beware `-d`, dragons be here
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/at_least_two.rs b/examples/at_least_two.rs
index 683db50..a4eb002 100644
--- a/examples/at_least_two.rs
+++ b/examples/at_least_two.rs
@@ -1,5 +1,20 @@
 //! How to require presence of at least N values,
 //! like `val1 val2 ... valN ... valM`.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     at_least_two <foos>...
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! ARGS:
+//!     <foos>...
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/basic.rs b/examples/basic.rs
index 510e0e0..33e4415 100644
--- a/examples/basic.rs
+++ b/examples/basic.rs
@@ -1,4 +1,28 @@
 //! A somewhat comprehensive example of a typical `StructOpt` usage.use
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! basic 0.3.25
+//! A basic example
+//!
+//! USAGE:
+//!     basic [FLAGS] [OPTIONS] --output <output> [--] [FILE]...
+//!
+//! FLAGS:
+//!     -d, --debug      Activate debug mode
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!     -v, --verbose    Verbose mode (-v, -vv, -vvv, etc.)
+//!
+//! OPTIONS:
+//!     -l, --level <level>...     admin_level to consider
+//!     -c, --nb-cars <nb-cars>    Number of cars
+//!     -o, --output <output>      Output file
+//!     -s, --speed <speed>        Set speed [default: 42]
+//!
+//! ARGS:
+//!     <FILE>...    Files to process
+//! -----------------------------------------------------
 
 use std::path::PathBuf;
 use structopt::StructOpt;
diff --git a/examples/deny_missing_docs.rs b/examples/deny_missing_docs.rs
index 82b1e63..05ceca9 100644
--- a/examples/deny_missing_docs.rs
+++ b/examples/deny_missing_docs.rs
@@ -10,6 +10,26 @@
 // https://github.com/rust-lang/rust/issues/24584 is fixed
 
 //! A test to check that structopt compiles with deny(missing_docs)
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//! Some subcommands
+//!
+//! USAGE:
+//!     deny_missing_docs [FLAGS] [SUBCOMMAND]
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!     -v
+//!
+//! SUBCOMMANDS:
+//!     a       command A
+//!     b       command B
+//!     c       command C
+//!     help    Prints this message or the help of the given subcommand(s)
+//! -----------------------------------------------------
 
 #![deny(missing_docs)]
 
diff --git a/examples/doc_comments.rs b/examples/doc_comments.rs
index 810101f..3d22152 100644
--- a/examples/doc_comments.rs
+++ b/examples/doc_comments.rs
@@ -1,4 +1,54 @@
 //! How to use doc comments in place of `help/long_help`.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! basic 0.3.25
+//! A basic example for the usage of doc comments as replacement of the arguments `help`, `long_help`, `about` and
+//! `long_about`
+//!
+//! USAGE:
+//!     doc_comments [FLAGS] <SUBCOMMAND>
+//!
+//! FLAGS:
+//!     -f, --first-flag
+//!             Just use doc comments to replace `help`, `long_help`, `about` or `long_about` input
+//!
+//!     -h, --help
+//!             Prints help information
+//!
+//!     -s, --second-flag
+//!             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.
+//!     -t, --third-flag
+//!             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
+//!
+//!     -V, --version
+//!             Prints version information
+//!
+//!
+//! SUBCOMMANDS:
+//!     first     The same rules described previously for flags. Are also true for in regards of sub-commands
+//!     help      Prints this message or the help of the given subcommand(s)
+//!     second    Applicable for both `about` an `help`
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/enum_in_args.rs b/examples/enum_in_args.rs
index 70347da..0722140 100644
--- a/examples/enum_in_args.rs
+++ b/examples/enum_in_args.rs
@@ -1,4 +1,19 @@
 //! How to use `arg_enum!` with `StructOpt`.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     enum_in_args <i>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! ARGS:
+//!     <i>    Important argument [possible values: Foo, Bar, FooBar]
+//! -----------------------------------------------------
 
 use clap::arg_enum;
 use structopt::StructOpt;
diff --git a/examples/enum_in_args_with_strum.rs b/examples/enum_in_args_with_strum.rs
index a045a48..7893e78 100644
--- a/examples/enum_in_args_with_strum.rs
+++ b/examples/enum_in_args_with_strum.rs
@@ -1,3 +1,18 @@
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//! 
+//! USAGE:
+//!     enum_in_args_with_strum [OPTIONS]
+//! 
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//! 
+//! OPTIONS:
+//!         --format <format>     [default: txt]  [possible values: txt, md, html]
+//! -----------------------------------------------------
+
 use structopt::StructOpt;
 use strum::{EnumString, EnumVariantNames, VariantNames};
 
diff --git a/examples/enum_tuple.rs b/examples/enum_tuple.rs
index 0bad2e6..a88adc2 100644
--- a/examples/enum_tuple.rs
+++ b/examples/enum_tuple.rs
@@ -1,4 +1,20 @@
 //! How to extract subcommands' args into external structs.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! classify 0.3.25
+//!
+//! USAGE:
+//!     enum_tuple <SUBCOMMAND>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! SUBCOMMANDS:
+//!     foo
+//!     help    Prints this message or the help of the given subcommand(s)
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/env.rs b/examples/env.rs
index 0477089..437f3c6 100644
--- a/examples/env.rs
+++ b/examples/env.rs
@@ -1,5 +1,22 @@
 //! How to use environment variable fallback an how it
 //! interacts with `default_value`.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! env 0.3.25
+//! Example for allowing to specify options via environment variables
+//!
+//! USAGE:
+//!     env [OPTIONS] --api-url <api-url>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! OPTIONS:
+//!         --api-url <api-url>    URL for the API server [env: API_URL=]
+//!         --retries <retries>    Number of retries [env: RETRIES=]  [default: 5]
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/example.rs b/examples/example.rs
index 71cc124..4dfd341 100644
--- a/examples/example.rs
+++ b/examples/example.rs
@@ -1,4 +1,27 @@
 //! Somewhat complex example of usage of structopt.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! example 0.3.25
+//! An example of StructOpt usage
+//!
+//! USAGE:
+//!     example [FLAGS] [OPTIONS] <input> [--] [output]
+//!
+//! FLAGS:
+//!     -d, --debug      Activate debug mode
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! OPTIONS:
+//!         --log <log>         Log file, stdout if no file, no logging if not present
+//!         --optv <optv>...
+//!     -s, --speed <speed>     Set speed [default: 42]
+//!
+//! ARGS:
+//!     <input>     Input file
+//!     <output>    Output file, stdout if not present
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/flatten.rs b/examples/flatten.rs
index d51647f..19208ec 100644
--- a/examples/flatten.rs
+++ b/examples/flatten.rs
@@ -1,4 +1,21 @@
 //! How to use flattening.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     flatten [FLAGS] -g <group> -u <user>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!     -v               switch verbosity on
+//!
+//! OPTIONS:
+//!     -g <group>        daemon group
+//!     -u <user>         daemon user
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/gen_completions.rs b/examples/gen_completions.rs
index 6dbd97f..e9e9693 100644
--- a/examples/gen_completions.rs
+++ b/examples/gen_completions.rs
@@ -6,6 +6,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//! An example of how to generate bash completions with structopt
+//!
+//! USAGE:
+//!     gen_completions [FLAGS]
+//!
+//! FLAGS:
+//!     -d, --debug      Activate debug mode
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//! -----------------------------------------------------
+
 use structopt::clap::Shell;
 use structopt::StructOpt;
 
diff --git a/examples/git.rs b/examples/git.rs
index 494e9d1..6e4137b 100644
--- a/examples/git.rs
+++ b/examples/git.rs
@@ -2,6 +2,24 @@
 //! as well as a demonstration of adding documentation to subcommands.
 //! Documentation can be added either through doc comments or
 //! `help`/`about` attributes.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! git 0.3.25
+//! the stupid content tracker
+//!
+//! USAGE:
+//!     git <SUBCOMMAND>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! SUBCOMMANDS:
+//!     add
+//!     fetch    fetch branches from remote repository
+//!     help     Prints this message or the help of the given subcommand(s)
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/group.rs b/examples/group.rs
index d53de6a..16ca366 100644
--- a/examples/group.rs
+++ b/examples/group.rs
@@ -1,4 +1,24 @@
 //! How to use `clap::Arg::group`
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     group [OPTIONS] <--method <method>|--get|--head|--post|--put|--delete>
+//!
+//! FLAGS:
+//!         --delete     HTTP DELETE
+//!         --get        HTTP GET
+//!     -h, --help       Prints help information
+//!         --head       HTTP HEAD
+//!         --post       HTTP POST
+//!         --put        HTTP PUT
+//!     -V, --version    Prints version information
+//!
+//! OPTIONS:
+//!         --method <method>    Set a custom HTTP verb
+//! -----------------------------------------------------
 
 use structopt::{clap::ArgGroup, StructOpt};
 
diff --git a/examples/keyvalue.rs b/examples/keyvalue.rs
index 12ce6fc..92acafa 100644
--- a/examples/keyvalue.rs
+++ b/examples/keyvalue.rs
@@ -1,4 +1,19 @@
 //! How to parse "key=value" pairs with structopt.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     keyvalue [OPTIONS]
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! OPTIONS:
+//!     -D <defines>...
+//! -----------------------------------------------------
 
 use std::error::Error;
 use structopt::StructOpt;
diff --git a/examples/negative_flag.rs b/examples/negative_flag.rs
index b178bf5..0d9337c 100644
--- a/examples/negative_flag.rs
+++ b/examples/negative_flag.rs
@@ -1,5 +1,18 @@
 //! How to add `no-thing` flag which is `true` by default and
 //! `false` if passed.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     negative_flag [FLAGS]
+//!
+//! FLAGS:
+//!     -h, --help          Prints help information
+//!     -V, --version       Prints version information
+//!         --no-verbose
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/no_version.rs b/examples/no_version.rs
index a542ec1..5fc6274 100644
--- a/examples/no_version.rs
+++ b/examples/no_version.rs
@@ -1,4 +1,15 @@
 //! How to completely remove version.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! no_version
+//!
+//! USAGE:
+//!     no_version
+//!
+//! FLAGS:
+//!     -h, --help    Prints help information
+//! -----------------------------------------------------
 
 use structopt::clap::AppSettings;
 use structopt::StructOpt;
diff --git a/examples/rename_all.rs b/examples/rename_all.rs
index c7c3538..6958c01 100644
--- a/examples/rename_all.rs
+++ b/examples/rename_all.rs
@@ -20,7 +20,24 @@
 //!
 //! - **Lower Case**: Keep all letters lowercase and remove word boundaries.
 //!
-//! - **Upper Case**: Keep all letters upperrcase and remove word boundaries.
+//! - **Upper Case**: Keep all letters uppercase and remove word boundaries.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! rename_all 0.3.25
+//!
+//! USAGE:
+//!     rename_all <SUBCOMMAND>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! SUBCOMMANDS:
+//!     FIRST_COMMAND    A screaming loud first command. Only use if necessary
+//!     SecondCommand    Not nearly as loud as the first command
+//!     help             Prints this message or the help of the given subcommand(s)
+//! -----------------------------------------------------
 
 use structopt::StructOpt;
 
diff --git a/examples/required_if.rs b/examples/required_if.rs
index cb6b414..e3497b2 100644
--- a/examples/required_if.rs
+++ b/examples/required_if.rs
@@ -1,4 +1,23 @@
 //! How to use `required_if` with structopt.
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     required_if -o <out-type> [FILE]
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! OPTIONS:
+//!     -o <out-type>        Where to write the output: to `stdout` or `file`
+//!
+//! ARGS:
+//!     <FILE>    File name: only required when `out-type` is set to `file`
+//! -----------------------------------------------------
+
 use structopt::StructOpt;
 
 #[derive(Debug, StructOpt, PartialEq)]
diff --git a/examples/subcommand_aliases.rs b/examples/subcommand_aliases.rs
index 30b8cc3..1837ddb 100644
--- a/examples/subcommand_aliases.rs
+++ b/examples/subcommand_aliases.rs
@@ -1,4 +1,21 @@
 //! How to assign some aliases to subcommands
+//!
+//! Running this example with --help prints this message:
+//! -----------------------------------------------------
+//! structopt 0.3.25
+//!
+//! USAGE:
+//!     subcommand_aliases <SUBCOMMAND>
+//!
+//! FLAGS:
+//!     -h, --help       Prints help information
+//!     -V, --version    Prints version information
+//!
+//! SUBCOMMANDS:
+//!     bar
+//!     foo
+//!     help    Prints this message or the help of the given subcommand(s)
+//! -----------------------------------------------------
 
 use structopt::clap::AppSettings;
 use structopt::StructOpt;
diff --git a/src/lib.rs b/src/lib.rs
index f7c5ce7..92d93ab 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,6 +11,14 @@
 
 //! This crate defines the `StructOpt` trait and its custom derive.
 //!
+//! ## Maintenance
+//!
+//! As clap v3 is now out, and the structopt features are integrated
+//! into (almost as-is), structopt is now in maintenance mode: no new
+//! feature will be added.
+//!
+//! Bugs will be fixed, and documentation improvements will be accepted.
+//!
 //! ## Features
 //!
 //! If you want to disable all the `clap` features (colors,
@@ -60,7 +68,7 @@
 //!
 //! First, let's look at the example:
 //!
-//! ```should_panic
+//! ```
 //! use std::path::PathBuf;
 //! use structopt::StructOpt;
 //!
@@ -95,7 +103,10 @@
 //! }
 //!
 //! fn main() {
+//! #   /*
 //!     let opt = Opt::from_args();
+//! #   */
+//! #   let opt = Opt::from_iter(&["binary", "-o", "stdout", "input"]);
 //!     println!("{:?}", opt);
 //! }
 //! ```
@@ -134,13 +145,17 @@
 //!     They are what used to be explicit `#[structopt(raw(...))]` attrs in pre-0.3 `structopt`
 //!
 //! Every `structopt attribute` looks like comma-separated sequence of methods:
-//! ```rust,ignore
+//! ```
+//! # #[derive(structopt::StructOpt)] struct S {
+//! #
 //! #[structopt(
 //!     short, // method with no arguments - always magical
 //!     long = "--long-option", // method with one argument
 //!     required_if("out", "file"), // method with one and more args
 //!     parse(from_os_str = path::to::parser) // some magical methods have their own syntax
 //! )]
+//! #
+//! # s: () } mod path { pub(crate) mod to { pub(crate) fn parser(_: &std::ffi::OsStr) {} }}
 //! ```
 //!
 //! `#[structopt(...)]` attributes can be placed on top of `struct`, `enum`,
@@ -172,13 +187,19 @@
 //! ## Raw methods
 //!
 //! They are the reason why `structopt` is so flexible. **Every and each method from
-//! `clap::App/Arg` can be used this way!**
+//! `clap::App/Arg` can be used this way!** See the [`clap::App`
+//! methods](https://docs.rs/clap/2/clap/struct.App.html) and [`clap::Arg`
+//! methods](https://docs.rs/clap/2/clap/struct.Arg.html).
 //!
-//! ```ignore
+//! ```
+//! # #[derive(structopt::StructOpt)] struct S {
+//! #
 //! #[structopt(
 //!     global = true, // name = arg form, neat for one-arg methods
 //!     required_if("out", "file") // name(arg1, arg2, ...) form.
 //! )]
+//! #
+//! # s: String }
 //! ```
 //!
 //! The first form can only be used for methods which take only one argument.
@@ -322,7 +343,7 @@
 //!
 //! ## Type magic
 //!
-//! One of major things that makes `structopt` so awesome is it's type magic.
+//! One of major things that makes `structopt` so awesome is its type magic.
 //! Do you want optional positional argument? Use `Option<T>`! Or perhaps optional argument
 //! that optionally takes value (`[--opt=[val]]`)? Use `Option<Option<T>>`!
 //!
@@ -435,7 +456,6 @@
 //!     /// for its type (in this case 0).
 //!     #[structopt(skip)]
 //!     skipped: u32,
-//!
 //! }
 //!
 //! # Opt::from_iter(
@@ -452,7 +472,7 @@
 //! #[derive(StructOpt)]
 //! struct Opt {
 //!     #[structopt(default_value = "", long)]
-//!     prefix: String
+//!     prefix: String,
 //! }
 //! ```
 //!
@@ -474,7 +494,7 @@
 //! struct Opt {
 //!     // just leave the `= "..."` part and structopt will figure it for you
 //!     #[structopt(default_value, long)]
-//!     prefix: String // `String` implements both `Default` and `ToString`
+//!     prefix: String, // `String` implements both `Default` and `ToString`
 //! }
 //! ```
 //!
@@ -499,8 +519,8 @@
 //! #[derive(StructOpt)]
 //! #[structopt(about = "I am a program and I work, just pass `-h`")]
 //! struct Foo {
-//!   #[structopt(short, help = "Pass `-h` and you'll see me!")]
-//!   bar: String
+//!     #[structopt(short, help = "Pass `-h` and you'll see me!")]
+//!     bar: String,
 //! }
 //! ```
 //!
@@ -513,8 +533,8 @@
 //! #[derive(StructOpt)]
 //! /// I am a program and I work, just pass `-h`
 //! struct Foo {
-//!   /// Pass `-h` and you'll see me!
-//!   bar: String
+//!     /// Pass `-h` and you'll see me!
+//!     bar: String,
 //! }
 //! ```
 //!
@@ -555,7 +575,7 @@
 //!     /// until I'll have destroyed humanity. Enjoy your
 //!     /// pathetic existence, you mere mortals.
 //!     #[structopt(long)]
-//!     kill_all_humans: bool
+//!     kill_all_humans: bool,
 //! }
 //! ```
 //!
@@ -632,7 +652,7 @@
 //! Also, `structopt` will *still* remove leading and trailing blank lines so
 //! these formats are equivalent:
 //!
-//! ```ignore
+//! ```
 //! /** This is a doc comment
 //!
 //! Hello! */
@@ -646,6 +666,8 @@
 //! /// This is a doc comment
 //! ///
 //! /// Hello!
+//! #
+//! # mod m {}
 //! ```
 //! ______________
 //!
@@ -665,8 +687,8 @@
 //!
 //! #[derive(StructOpt)]
 //! struct Foo {
-//!   #[structopt(short, long, env = "PARAMETER_VALUE")]
-//!   parameter_value: String
+//!     #[structopt(short, long, env = "PARAMETER_VALUE")]
+//!     parameter_value: String,
 //! }
 //! ```
 //!
@@ -688,8 +710,8 @@
 //!
 //! #[derive(StructOpt)]
 //! struct Foo {
-//!   #[structopt(long = "secret", env = "SECRET_VALUE", hide_env_values = true)]
-//!   secret_value: String
+//!     #[structopt(long = "secret", env = "SECRET_VALUE", hide_env_values = true)]
+//!     secret_value: String,
 //! }
 //! ```
 //!
@@ -707,8 +729,8 @@
 //!
 //! #[derive(StructOpt)]
 //! struct Foo {
-//!   #[structopt(long = "secret", env)]
-//!   secret_value: String
+//!     #[structopt(long = "secret", env)]
+//!     secret_value: String,
 //! }
 //! ```
 //!
@@ -774,21 +796,21 @@
 //!         #[structopt(short)]
 //!         patch: bool,
 //!         #[structopt(parse(from_os_str))]
-//!         files: Vec<PathBuf>
+//!         files: Vec<PathBuf>,
 //!     },
 //!     Fetch {
 //!         #[structopt(long)]
 //!         dry_run: bool,
 //!         #[structopt(long)]
 //!         all: bool,
-//!         repository: Option<String>
+//!         repository: Option<String>,
 //!     },
 //!     Commit {
 //!         #[structopt(short)]
 //!         message: Option<String>,
 //!         #[structopt(short)]
-//!         all: bool
-//!     }
+//!         all: bool,
+//!     },
 //! }
 //! ```
 //!
@@ -807,22 +829,22 @@
 //!     supervising_faerie: String,
 //!     /// The faerie tree this cookie is being made in.
 //!     tree: Option<String>,
-//!     #[structopt(subcommand)]  // Note that we mark a field as a subcommand
-//!     cmd: Command
+//!     #[structopt(subcommand)] // Note that we mark a field as a subcommand
+//!     cmd: Command,
 //! }
 //!
 //! #[derive(StructOpt)]
 //! enum Command {
 //!     /// Pound acorns into flour for cookie dough.
 //!     Pound {
-//!         acorns: u32
+//!         acorns: u32,
 //!     },
 //!     /// Add magical sparkles -- the secret ingredient!
 //!     Sparkle {
 //!         #[structopt(short, parse(from_occurrences))]
 //!         magicality: u64,
 //!         #[structopt(short)]
-//!         color: String
+//!         color: String,
 //!     },
 //!     Finish(Finish),
 //! }
@@ -832,19 +854,19 @@
 //! struct Finish {
 //!     #[structopt(short)]
 //!     time: u32,
-//!     #[structopt(subcommand)]  // Note that we mark a field as a subcommand
-//!     finish_type: FinishType
+//!     #[structopt(subcommand)] // Note that we mark a field as a subcommand
+//!     finish_type: FinishType,
 //! }
 //!
 //! // subsubcommand!
 //! #[derive(StructOpt)]
 //! enum FinishType {
 //!     Glaze {
-//!         applications: u32
+//!         applications: u32,
 //!     },
 //!     Powder {
 //!         flavor: String,
-//!         dips: u32
+//!         dips: u32,
 //!     }
 //! }
 //! ```
@@ -868,14 +890,14 @@
 //! struct Foo {
 //!     file: String,
 //!     #[structopt(subcommand)]
-//!     cmd: Option<Command>
+//!     cmd: Option<Command>,
 //! }
 //!
 //! #[derive(StructOpt)]
 //! enum Command {
 //!     Bar,
 //!     Baz,
-//!     Quux
+//!     Quux,
 //! }
 //! ```
 //!
@@ -953,7 +975,7 @@
 //!     BaseCli(BaseCli),
 //!     Dex {
 //!         arg2: i32,
-//!     }
+//!     },
 //! }
 //! ```
 //!
@@ -1068,10 +1090,10 @@
 //!
 //! // a struct with single custom argument
 //! #[derive(StructOpt)]
-//! struct GenericArgs<T:FromStr> where <T as FromStr>::Err: fmt::Display + fmt::Debug {
+//! struct GenericArgs<T: FromStr> where <T as FromStr>::Err: fmt::Display + fmt::Debug {
 //!     generic_arg_1: String,
 //!     generic_arg_2: String,
-//!     custom_arg_1: T
+//!     custom_arg_1: T,
 //! }
 //! ```
 //!
@@ -1081,11 +1103,11 @@
 //! # use structopt::StructOpt;
 //! // a struct with multiple custom arguments in a substructure
 //! #[derive(StructOpt)]
-//! struct GenericArgs<T:StructOpt> {
+//! struct GenericArgs<T: StructOpt> {
 //!     generic_arg_1: String,
 //!     generic_arg_2: String,
 //!     #[structopt(flatten)]
-//!     custom_args: T
+//!     custom_args: T,
 //! }
 //! ```
 
diff --git a/tests/issues.rs b/tests/issues.rs
index 5860c49..3f9e1af 100644
--- a/tests/issues.rs
+++ b/tests/issues.rs
@@ -117,6 +117,34 @@
 }
 
 #[test]
+fn issue_418() {
+    use structopt::StructOpt;
+
+    #[derive(Debug, StructOpt)]
+    struct Opts {
+        #[structopt(subcommand)]
+        /// The command to run
+        command: Command,
+    }
+
+    #[derive(Debug, StructOpt)]
+    enum Command {
+        /// Reticulate the splines
+        #[structopt(visible_alias = "ret")]
+        Reticulate {
+            /// How many splines
+            num_splines: u8,
+        },
+        /// Frobnicate the rest
+        #[structopt(visible_alias = "frob")]
+        Frobnicate,
+    }
+
+    let help = get_long_help::<Opts>();
+    assert!(help.contains("Reticulate the splines [aliases: ret]"));
+}
+
+#[test]
 fn issue_490() {
     use std::iter::FromIterator;
     use std::str::FromStr;
diff --git a/tests/ui/skip_without_default.stderr b/tests/ui/skip_without_default.stderr
index b5d702a..d08be0c 100644
--- a/tests/ui/skip_without_default.stderr
+++ b/tests/ui/skip_without_default.stderr
@@ -1,7 +1,7 @@
 error[E0277]: the trait bound `Kind: Default` is not satisfied
-  --> $DIR/skip_without_default.rs:22:17
-   |
-22 |     #[structopt(skip)]
-   |                 ^^^^ the trait `Default` is not implemented for `Kind`
-   |
-   = note: required by `std::default::Default::default`
+   --> $DIR/skip_without_default.rs:22:17
+    |
+22  |     #[structopt(skip)]
+    |                 ^^^^ the trait `Default` is not implemented for `Kind`
+    |
+note: required by `std::default::Default::default`