[docs] Add output to all examples

When viewing examples, it is very hard to figure out what they do without running them, which requires substantial efforts.  I have added the output of all examples at the top.

Also, two tiny spelling mistakes - in the readme and in the rename_all.

In case anyone wants to auto-generate something similar, I used this helper script, and made a few minor line manipulations afterwards.

```bash

run() {
  RES=$(cargo run -q --example "$1" -- --help 2> /dev/null | sed -e 's#^#//! #' )
  { echo "//! Running this example with --help prints this message:" ; echo "//! -----------------------------------------------------" ; echo "$RES" ; echo "//! -----------------------------------------------------" ; echo "" ; cat "examples/$1.rs" ; } > "$1.rs"
  rm "examples/$1.rs"
  mv "$1.rs" "examples/"
}

run after_help
run at_least_two
```

examples/README.md

@@ -31,7 +31,7 @@ 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`.
+How to use environment variable fallback and how it interacts with `default_value`.
 
 ### [Advanced](example.rs)
 

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;
 

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;
 

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;

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)]
 

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;
 

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;

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};
 

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;
 

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;
 

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;
 

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;
 

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;
 

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;
 

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};
 

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;