Update structopt to 0.3.26
Test: cd external/rust/crates && atest --host -c
Change-Id: Iaeee8c2cf42b73912e007f71bdcaeb1db91db18c
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;