docs: updates for deprecations and new features

README.md

@@ -53,6 +53,7 @@ Below are a few of the features which `clap` supports, full descriptions and usa
 * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the `examples/12_TypedValues.rs`. You can also use `clap`s `simple_enum!` or `arg_enum!` macro to create an enum with variants that automatically implements `std::str::FromStr`. See `examples/13a_EnumValuesAutomatic.rs` for details and performs an ascii case insensitive parse from a `string`->`enum`.
 * **Suggestions**: Suggests corrections when the user enter's a typo. For example, if you defined a `--myoption <value>` argument, and the user mistakenly typed `--moyption value` (notice `y` and `o` switched), they would receive a `Did you mean '--myoption' ?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features')
 * **Colorized (Red) Errors**: Error message are printed in red text (this feature can optionally be disabled, see 'Optional Dependencies / Features').
+* **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands.
 
 ## Quick Example
 
@@ -369,7 +370,10 @@ Although I do my best to keep breaking changes to a minimum, being that this a s
 
 Old method names will be left around for some time.
 
+* As of 0.10.0
+ - `SubCommand::new()` -> `SubCommand::with_name()`
+ - `App::error_on_no_subcommand()` -> `App::subcommand_required()`
 * As of 0.6.8
-  - `Arg::new()` -> `Arg::with_name()`
-  - `Arg::mutually_excludes()` -> `Arg::conflicts_with()`
-  - `Arg::mutually_excludes_all()` -> `Arg::conflicts_with_all()`
+ - `Arg::new()` -> `Arg::with_name()`
+ - `Arg::mutually_excludes()` -> `Arg::conflicts_with()`
+ - `Arg::mutually_excludes_all()` -> `Arg::conflicts_with_all()`

src/args/arg.rs

@@ -649,12 +649,17 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
         self
     }
 
-    /// Specifies that an argument applies to and will be available to all child subcommands.
+    /// Specifies that an argument can be matched to all child subcommands.
     ///
     /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands)
     ///
     /// **NOTE:** Global arguments *cannot* be required.
     ///
+    /// **NOTE:** Global arguments, when matched, *only* exist in the command's matches that they
+    /// were matched to. For example, if you defined a `--flag` global argument in the top most
+    /// parent command, but the user supplied the arguments `top cmd1 cmd2 --flag` *only* `cmd2`'s
+    /// `ArgMatches` would return `true` if tested for `.is_present("flag")`.
+    ///
     /// # Example
     ///
     /// ```no_run

src/lib.rs

@@ -56,6 +56,7 @@
 //! * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the `examples/12_TypedValues.rs`. You can also use `clap`s `simple_enum!` or `arg_enum!` macro to create an enum with variants that automatically implements `std::str::FromStr`. See `examples/13a_EnumValuesAutomatic.rs` for details and performs an ascii case insensitive parse from a `string`->`enum`.
 //! * **Suggestions**: Suggests corrections when the user enter's a typo. For example, if you defined a `--myoption <value>` argument, and the user mistakenly typed `--moyption value` (notice `y` and `o` switched), they would receive a `Did you mean '--myoption' ?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features')
 //! * **Colorized (Red) Errors**: Error message are printed in red text (this feature can optionally be disabled, see 'Optional Dependencies / Features').
+//! * **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands.
 //!
 //! ## Quick Example
 //!
@@ -372,6 +373,9 @@
 //!
 //! Old method names will be left around for some time.
 //!
+//! * As of 0.10.0
+//!  - `SubCommand::new()` -> `SubCommand::with_name()`
+//!  - `App::error_on_no_subcommand()` -> `App::subcommand_required()`
 //! * As of 0.6.8
 //!   - `Arg::new()` -> `Arg::with_name()`
 //!   - `Arg::mutually_excludes()` -> `Arg::conflicts_with()`