diff --git a/examples/rename_all.rs b/examples/rename_all.rs
index 5f10c9ba..36ac12e7 100644
--- a/examples/rename_all.rs
+++ b/examples/rename_all.rs
@@ -1,7 +1,7 @@
 //! Example on how the `rename_all` parameter works.
 //!
 //! `rename_all` can be used to override the casing style used during argument
-//! generation. Default the `verbatim-case` style will be used but there is a wide
+//! generation. By default the `verbatim-case` style will be used but there are a wide
 //! variety of other styles available.
 //!
 //! ## Supported styles overview:
@@ -41,7 +41,7 @@ enum Opt {
     #[structopt(rename_all = "pascal_case")]
     SecondCommand {
         // We can also override it again on a single field.
-        /// Nice quite flag. No one is annoyed.
+        /// Nice quiet flag. No one is annoyed.
         #[structopt(rename_all = "snake_case", long)]
         bar_option: bool,
 
diff --git a/src/lib.rs b/src/lib.rs
index 6d500373..206476af 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -141,16 +141,19 @@
 //! (sub-)command:
 //!
 //!  - short (e.g. `-h`),
-//!  - long  (e.g. `--help`)
+//!  - long (e.g. `--help`)
 //!  - and positional.
 //!
-//! Like clap, structopt defaults to creation positional arguments.
+//! Like clap, structopt defaults to creating positional arguments.
 //!
-//! If you want to generate a long argument you can either specify `long`
-//! to get a long flag generated by converting  the field name to
-//! `kebab-case` or `long = $NAME`. For short arguments `short` will use
-//! the first letter of the field name but equivalent to the long option
-//! its also possible to use a custom letter through `short = $LETTER`.
+//! If you want to generate a long argument you can specify either
+//! `long = $NAME`, or just `long` to get a long flag generated using
+//! the field name.  The generated casing style can be modified using
+//! the `rename_all` attribute. See the `rename_all` example for more.
+//!
+//! For short arguments, `short` will use the first letter of the
+//! field name by default, but just like the long option it's also
+//! possible to use a custom letter through `short = $LETTER`.
 //!
 //! If an argument is renamed using `name = $NAME` any following call to
 //! `short` or `long` will use the new name.
@@ -162,6 +165,7 @@
 //! use structopt::StructOpt;
 //!
 //! #[derive(StructOpt)]
+//! #[structopt(rename_all = "kebab-case")]
 //! struct Opt {
 //!     /// This option can be specified with something like `--foo-option
 //!     /// value` or `--foo-option=value`
@@ -187,7 +191,10 @@
 //!     my_positional: String,
 //! }
 //!
-//! # fn main() {}
+//! # fn main() {
+//! # Opt::from_clap(&Opt::clap().get_matches_from(
+//! #    &["test", "--foo-option", "", "-b", "", "--baz", "", "--custom", "", "positional"]));
+//! # }
 //! ```
 //!
 //! ## Help messages