depr(SubCommand/App): several methods and functions for stable release

SubCommand::new() -> SubCommand::with_name()
App::error_on_no_subcommand() -> App::subcommand_required()

src/app.rs

@@ -234,6 +234,8 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{
         self
     }
 
+    /// **WARNING:** This method is deprecated. Use `.subcommand_required(true)` instead.
+    ///
     /// Allows specifying that if no subcommand is present at runtime, error and exit gracefully
     ///
     /// **NOTE:** This defaults to false (subcommands do *not* need to be present)
@@ -251,6 +253,23 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{
         self
     }
 
+    /// Allows specifying that if no subcommand is present at runtime, error and exit gracefully
+    ///
+    /// **NOTE:** This defaults to false (subcommands do *not* need to be present)
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use clap::App;
+    /// # let app = App::new("myprog")
+    /// .subcommands_negate_reqs(true)
+    /// # .get_matches();
+    /// ```
+    pub fn subcommand_required(mut self, n: bool) -> App<'a, 'v, 'ab, 'u, 'h, 'ar> {
+        self.no_sc_error = n;
+        self
+    }
+
     /// Sets a string of the version number to be displayed when displaying version or help
     /// information.
     ///

src/args/arg.rs

@@ -88,10 +88,14 @@ pub struct Arg<'n, 'l, 'h, 'g, 'p, 'r> {
     #[doc(hidden)]
     pub min_vals: Option<u8>,
     #[doc(hidden)]
-    pub empty_vals: bool
+    pub empty_vals: bool,
+    #[doc(hidden)]
+    pub global: bool
 }
 
 impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
+    /// **WARNING:** This function is deprecated. Use `Arg::with_name()` instead.
+    ///
     /// Creates a new instace of `Arg` using a unique string name.
     /// The name will be used by the library consumer to get information about
     /// whether or not the argument was used at runtime.
@@ -100,8 +104,6 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
     /// and positional arguments (i.e. those without a `-` or `--`) the name will also
     /// be displayed when the user prints the usage/help information of the program.
     ///
-    /// **NOTE:** this function is deprecated in favor of Arg::with_name() to stay consistent with
-    /// Rust APIs
     ///
     ///
     /// # Example
@@ -423,16 +425,15 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
         self
     }
 
+    /// **WARNING:** This method is deprecated. Use `.conflicts_with()` instead.
+    ///
     /// Sets a mutually exclusive argument by name. I.e. when using this argument,
     /// the following argument can't be present.
     ///
     /// **NOTE:** Mutually exclusive rules take precedence over being required
     /// by default. Mutually exclusive rules only need to be set for one of the two
     /// arguments, they do not need to be set for each.
     ///
-    /// **NOTE:** This method is deprecated in favor of `conflicts_with()`
-    ///
-    ///
     /// # Example
     ///
     /// ```no_run
@@ -450,16 +451,15 @@ impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
         self
     }
 
+    /// **WARNING:** This method is deprecated. Use `conflicts_with_all()` instead.
+    ///
     /// Sets a mutually exclusive arguments by names. I.e. when using this argument,
     /// the following argument can't be present.
     ///
     /// **NOTE:** Mutually exclusive rules take precedence over being required
     /// by default. Mutually exclusive rules only need to be set for one of the two
     /// arguments, they do not need to be set for each.
     ///
-    /// **NOTE:** This method is deprecated in favor of `conflicts_with_all()`
-    ///
-    ///
     /// # Example
     ///
     /// ```no_run
@@ -646,6 +646,25 @@ 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 subcommands, both
+    /// children, and parent commands.
+    ///
+    /// **NOTE:** Global arguments *cannot* be required.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use clap::{App, Arg};
+    /// # let matches = App::new("myprog")
+    /// #                 .arg(
+    /// # Arg::with_name("debug")
+    /// .global(true)
+    /// # ).get_matches();
+    pub fn global(mut self, g: bool) -> Arg<'n, 'l, 'h, 'g, 'p, 'r> {
+        self.global = g;
+        self
+    }
+
     /// Allows an argument to accept explicit empty values. An empty value must be specified at the
     /// command line with an explicit `""`, or `''`
     ///

src/args/subcommand.rs

@@ -28,6 +28,23 @@ pub struct SubCommand<'n, 'a> {
 }
 
 impl<'n, 'a> SubCommand<'n, 'a> {
+    /// Creates a new instance of a subcommand requiring a name. Will be displayed
+    /// to the user when they print version or help and usage information.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use clap::{App, Arg, SubCommand};
+    /// # let prog = App::new("myprog").subcommand(
+    /// SubCommand::new("config")
+    /// # ).get_matches();
+    /// ```
+    pub fn with_name<'au, 'v, 'ab, 'u, 'h, 'ar>(name: &'ar str) -> App<'au, 'v, 'ab, 'u, 'h, 'ar> {
+        App::new(name)
+    }
+
+    /// **WARNING:** This function is deprecated. Use `SubCommand::with_name()` instead.
+    ///
     /// Creates a new instance of a subcommand requiring a name. Will be displayed
     /// to the user when they print version or help and usage information.
     ///