Update structopt to 0.3.26 am: 12ae7f8ab5 am: 8a646ada9d am: 1b851c6441t_frc_odp_330442040t_frc_odp_330442000t_frc_ase_330444010android-13.0.0_r83android-13.0.0_r82android-13.0.0_r81android-13.0.0_r80android-13.0.0_r79android-13.0.0_r78android-13.0.0_r77android-13.0.0_r76android-13.0.0_r75android-13.0.0_r74android-13.0.0_r73android-13.0.0_r72android-13.0.0_r71android-13.0.0_r70android-13.0.0_r69android-13.0.0_r68android-13.0.0_r67android-13.0.0_r66android-13.0.0_r65android-13.0.0_r64android-13.0.0_r63android-13.0.0_r62android-13.0.0_r61android-13.0.0_r60android-13.0.0_r59android-13.0.0_r58android-13.0.0_r57android-13.0.0_r56android-13.0.0_r55android-13.0.0_r54android-13.0.0_r53android-13.0.0_r52android-13.0.0_r51android-13.0.0_r50android-13.0.0_r49android-13.0.0_r48android-13.0.0_r47android-13.0.0_r46android-13.0.0_r45android-13.0.0_r44android-13.0.0_r43android-13.0.0_r42android-13.0.0_r41android-13.0.0_r40android-13.0.0_r39android-13.0.0_r38android-13.0.0_r37android-13.0.0_r36android-13.0.0_r35android-13.0.0_r34android-13.0.0_r33android-13.0.0_r32android-13.0.0_r30android-13.0.0_r29android-13.0.0_r28android-13.0.0_r27android-13.0.0_r24android-13.0.0_r23android-13.0.0_r22android-13.0.0_r21android-13.0.0_r20android-13.0.0_r19android-13.0.0_r18android-13.0.0_r17android-13.0.0_r16aml_go_odp_330912000aml_go_ads_330915100aml_go_ads_330915000aml_go_ads_330913000android13-qpr3-s9-releaseandroid13-qpr3-s8-releaseandroid13-qpr3-s7-releaseandroid13-qpr3-s6-releaseandroid13-qpr3-s5-releaseandroid13-qpr3-s4-releaseandroid13-qpr3-s3-releaseandroid13-qpr3-s2-releaseandroid13-qpr3-s14-releaseandroid13-qpr3-s13-releaseandroid13-qpr3-s12-releaseandroid13-qpr3-s11-releaseandroid13-qpr3-s10-releaseandroid13-qpr3-s1-releaseandroid13-qpr3-releaseandroid13-qpr3-c-s8-releaseandroid13-qpr3-c-s7-releaseandroid13-qpr3-c-s6-releaseandroid13-qpr3-c-s5-releaseandroid13-qpr3-c-s4-releaseandroid13-qpr3-c-s3-releaseandroid13-qpr3-c-s2-releaseandroid13-qpr3-c-s12-releaseandroid13-qpr3-c-s11-releaseandroid13-qpr3-c-s10-releaseandroid13-qpr3-c-s1-releaseandroid13-qpr2-s9-releaseandroid13-qpr2-s8-releaseandroid13-qpr2-s7-releaseandroid13-qpr2-s6-releaseandroid13-qpr2-s5-releaseandroid13-qpr2-s3-releaseandroid13-qpr2-s2-releaseandroid13-qpr2-s12-releaseandroid13-qpr2-s11-releaseandroid13-qpr2-s10-releaseandroid13-qpr2-s1-releaseandroid13-qpr2-releaseandroid13-qpr2-b-s1-releaseandroid13-qpr1-s8-releaseandroid13-qpr1-s7-releaseandroid13-qpr1-s6-releaseandroid13-qpr1-s5-releaseandroid13-qpr1-s4-releaseandroid13-qpr1-s3-releaseandroid13-qpr1-s2-releaseandroid13-qpr1-s1-releaseandroid13-qpr1-releaseandroid13-mainline-go-adservices-releaseandroid13-frc-odp-releaseandroid13-devandroid13-d4-s2-releaseandroid13-d4-s1-releaseandroid13-d4-releaseandroid13-d3-s1-releaseandroid13-d2-release

Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/structopt/+/2004098

Change-Id: Iaeedb47db3c80c735b079ff7391010f7c53dff8e

21 files changed, 382 insertions, 2 deletions

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 @@ 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)
 
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;