fix: Deprecate Macro API

Fixes #2835

README.md

@@ -371,34 +371,6 @@ fn main() {
 }
 ```
 
-#### Using Macros
-
-Finally there is a macro version, which is like a hybrid approach offering the speed of the
-builder pattern (the first example), but without all the verbosity.
-
-```rust,no_run
-use clap::clap_app;
-
-fn main() {
-    let matches = clap_app!(myapp =>
-        (version: "1.0")
-        (author: "Kevin K. <kbknapp@gmail.com>")
-        (about: "Does awesome things")
-        (@arg CONFIG: -c --config [FILE] "Sets a custom config file")
-        (@arg INPUT: +required "Sets the input file to use")
-        (@arg verbose: -v --verbose "Sets the level of verbosity")
-        (@subcommand test =>
-            (about: "controls testing features")
-            (version: "1.3")
-            (author: "Someone E. <someone_else@other.com>")
-            (@arg debug: -d --debug "Print debug information")
-        )
-    ).get_matches();
-
-    // Same as previous examples...
-}
-```
-
 #### Running it
 
 If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following would be output (except the first example where the help message sort of explains the Rust code).

benches/03_complex.rs

@@ -1,4 +1,4 @@
-use clap::{clap_app, App, AppSettings, Arg, ArgSettings};
+use clap::{App, AppSettings, Arg, ArgSettings};
 use criterion::{criterion_group, criterion_main, Criterion};
 
 static OPT3_VALS: [&str; 2] = ["fast", "slow"];
@@ -160,42 +160,6 @@ pub fn build_from_builder(c: &mut Criterion) {
     });
 }
 
-pub fn build_from_macros(c: &mut Criterion) {
-    c.bench_function("build_from_macros", |b| {
-        b.iter(|| {
-            clap_app!(claptests =>
-                    (version: "0.1")
-                    (about: "tests clap library")
-                    (author: "Kevin K. <kbknapp@gmail.com>")
-                    (@arg opt: -o --option +takes_value ... "tests options")
-                    (@arg positional: index(1) "tests positionals")
-                    (@arg flag: -f --flag ... +global "tests flags")
-                    (@arg flag2: -F conflicts_with[flag] requires[option2]
-                        "tests flags with exclusions")
-                    (@arg option2: --long_option_2 conflicts_with[option] requires[positional2]
-                        "tests long options with exclusions")
-                    (@arg positional2: index(2) "tests positionals with exclusions")
-                    (@arg option3: -O --Option +takes_value possible_value[fast slow]
-                        "tests options with specific value sets")
-                    (@arg positional3: index(3) ... possible_value[vi emacs]
-                        "tests positionals with specific values")
-                    (@arg multvals: --multvals +takes_value value_name[one two]
-                        "Tests multiple values, not mult occs")
-                    (@arg multvalsmo: --multvalsmo ... +takes_value value_name[one two]
-                        "Tests multiple values, not mult occs")
-                    (@arg minvals: --minvals2 min_values(1) ... +takes_value "Tests 2 min vals")
-                    (@arg maxvals: --maxvals3 ... +takes_value max_values(3) "Tests 3 max vals")
-                    (@subcommand subcmd =>
-                        (about: "tests subcommands")
-                        (version: "0.1")
-                        (author: "Kevin K. <kbknapp@gmail.com>")
-                        (@arg scoption: -o --option ... +takes_value "tests options")
-                        (@arg scpositional: index(1) "tests positionals"))
-            );
-        })
-    });
-}
-
 pub fn parse_complex(c: &mut Criterion) {
     c.bench_function("parse_complex", |b| {
         b.iter(|| create_app!().get_matches_from(vec![""]))
@@ -327,7 +291,6 @@ criterion_group!(
     benches,
     build_from_usage,
     build_from_builder,
-    build_from_macros,
     parse_complex,
     parse_complex_with_flag,
     parse_complex_with_opt,

src/macros.rs

@@ -295,6 +295,10 @@ macro_rules! app_from_crate {
 /// [`Arg::max_values(max)`]: crate::Arg::max_values()
 /// [`Arg::validator`]: crate::Arg::validator()
 /// [`Arg::conflicts_with`]: crate::Arg::conflicts_with()
+#[deprecated(
+    since = "3.0.0",
+    note = "Replaced with `App` builder API (with `From::from` for parsing usage) or `Parser` derive API (Issue #2835)"
+)]
 #[macro_export]
 macro_rules! clap_app {
     (@app ($builder:expr)) => { $builder };

tests/help.rs

@@ -1,6 +1,6 @@
 mod utils;
 
-use clap::{clap_app, App, AppSettings, Arg, ArgGroup, ArgSettings, ArgValue, ErrorKind};
+use clap::{App, AppSettings, Arg, ArgGroup, ArgSettings, ArgValue, ErrorKind};
 
 static REQUIRE_DELIM_HELP: &str = "test 1.3
 
@@ -707,11 +707,21 @@ fn help_subcommand() {
 
 #[test]
 fn req_last_arg_usage() {
-    let app = clap_app!(example =>
-        (version: "1.0")
-        (@arg FIRST: ... * "First")
-        (@arg SECOND: ... * +last "Second")
-    );
+    let app = App::new("example")
+        .version("1.0")
+        .arg(
+            Arg::new("FIRST")
+                .about("First")
+                .multiple_values(true)
+                .required(true),
+        )
+        .arg(
+            Arg::new("SECOND")
+                .about("Second")
+                .multiple_values(true)
+                .required(true)
+                .last(true),
+        );
     assert!(utils::compare_output(
         app,
         "example --help",