imp: Stabilize clap_app!

It was de-stabilized in 2.0.0 but hasn't been changed since.

This commit also updates docs to reflect that the "unstable" feature does nothing now.

.github/CONTRIBUTING.md

@@ -21,7 +21,7 @@ Contributions are always welcome! Please use the following guidelines when contr
     - `chore` - Catch all or things that have to do with the build system, etc
     - `examples` - Changes to existing example, or a new example
  * The `COMPONENT` is optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally
-5. Run the tests (`cargo test --no-std-features && cargo test --features="yaml unstable"`)
+5. Run the tests (`cargo test --no-std-features && cargo test --features yaml`)
 6. `git rebase` into concise commits and remove `--fixup`s (`git rebase -i HEAD~NUM` where `NUM` is number of commits back)
 7. Push your changes back to your fork (`git push origin $your-branch`)
 8. Create a pull request! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.)

Cargo.toml

@@ -35,7 +35,7 @@ suggestions = ["strsim"]
 color       = ["ansi_term", "libc"]
 wrap_help   = ["libc", "term_size"]
 yaml        = ["yaml-rust"]
-unstable    = [] # for building with unstable clap features (doesn't require nightly Rust)
+unstable    = [] # for building with unstable clap features (doesn't require nightly Rust) (currently none)
 nightly     = [] # for building with unstable Rust features (currently none)
 lints       = ["clippy"] # Requires nightly Rust
 debug       = [] # Enables debug messages

README.md

@@ -493,7 +493,10 @@ subcommands:
                 help: print debug information
 ```
 
-Now we create our `main.rs` file just like we would have with the previous two examples:
+Since this feature is not compiled in by default we need to enable a feature flag in Cargo.toml:
+Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}`.
+
+At last we create our `main.rs` file just like we would have with the previous two examples:
 
 ```rust
 // (Full example with detailed comments in examples/17_yaml.rs)
@@ -513,8 +516,6 @@ fn main() {
 }
 ```
 
-**NOTE**: The YAML and macro builder options require adding a special `features` flag when compiling `clap` because they are not compiled by default. Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}` for YAML, or `features = ["unstable"]` for the macro builder, in your `Cargo.toml`.
-
 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
 
 ```sh
@@ -632,7 +633,6 @@ features = [ "suggestions", "color" ]
 #### Opt-in features
 
 * **"yaml"**: Enables building CLIs from YAML documents. (builds dependency `yaml-rust`)
-* **"unstable"**: Enables clap features whoose API might change without a major version bump, but doesn't require nightly Rust. Currently `clap_app!`.
 
 ### Dependencies Tree
 
@@ -667,7 +667,7 @@ To test with all features both enabled and disabled, you can run theese commands
 
 ```sh
 $ cargo test --no-default-features
-$ cargo test --features "yaml unstable"
+$ cargo test --features yaml
 ```
 
 If you have a nightly compiler you can append `--features lints` to both commands

benches/03_complex.rs

@@ -134,8 +134,7 @@ fn create_app_builder(b: &mut Bencher) {
     });
 }
 
-#[cfg(feature = "unstable")]
-#[cfg_attr(feature = "unstable", bench)]
+#[bench]
 fn create_app_macros(b: &mut Bencher) {
     b.iter(|| {
         clap_app!(claptests =>

examples/01c_quick_example.rs

@@ -1,7 +1,6 @@
 #[macro_use]
 extern crate clap;
 
-#[cfg(feature = "unstable")]
 fn main() {
     // This example shows how to create an application with several arguments using macro builder.
     // It combines the simplicity of the from_usage methods and the performance of the Builder Pattern.
@@ -74,6 +73,3 @@ fn main() {
 
     // more program logic goes here...
 }
-
-#[cfg(not(feature = "unstable"))]
-fn main() {}

examples/18_builder_macro.rs

@@ -4,7 +4,6 @@ extern crate clap;
 // Note, there isn't a need for "use clap::{ ... };" Because the clap_app! macro uses
 // $crate:: internally
 
-#[cfg(feature = "unstable")]
 fn main() {
 
     // Validation example testing that a file exists
@@ -82,6 +81,3 @@ fn main() {
 
     // Continued program logic goes here...
 }
-
-#[cfg(not(feature = "unstable"))]
-fn main() {}

src/lib.rs

@@ -151,10 +151,8 @@
 //!
 //! The following combines the previous two examples by using the less verbose `from_usage` methods and the performance of the Builder Pattern.
 //!
-#![cfg_attr(not(feature="unstable"), doc=" ```ignore")]
-#![cfg_attr(    feature="unstable" , doc=" ```no_run")]
+//! ```no_run
 //! // (Full example with detailed comments in examples/01c_quick_example.rs)
-//! // Must be compiled with `--features unstable` (which doesn't require nightly Rust).
 //! //
 //! // This example demonstrates clap's "usage strings" method of creating arguments
 //! // which is less less verbose
@@ -214,7 +212,10 @@
 //!                 help: print debug information
 //! ```
 //!
-//! Now we create our `main.rs` file just like we would have with the previous two examples:
+//! Because this feature is not compiled in by default we need to enable a feature flag in Cargo.toml:
+//! Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}`.
+//!
+//! At last we create our `main.rs` file just like we would have with the previous two examples:
 //!
 //! ```ignore
 //! // (Full example with detailed comments in examples/17_yaml.rs)
@@ -234,8 +235,6 @@
 //! }
 //! ```
 //!
-//! **NOTE**: The YAML and macro builder options require adding a special `features` flag when compiling `clap` because they are not compiled by default. Simply change your `clap = "2"` to `clap = {version = "2", features = ["yaml"]}` for YAML, or `features = ["unstable"]` for the macro builder, in your `Cargo.toml`.
-//!
 //! 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
 //!
 //! ```text
@@ -353,7 +352,6 @@
 //! #### Opt-in features
 //!
 //! * **"yaml"**: Enables building CLIs from YAML documents.
-//! * **"unstable"**: Enables clap features whoose API might change without a major version bump. Doesn't require nightly Rust. Currently `clap_app!`.
 //!
 //! ### More Information
 //!
@@ -375,7 +373,7 @@
 //!
 //! ```sh
 //! $ cargo test --no-default-features
-//! $ cargo test --features "yaml unstable"
+//! $ cargo test --features yaml
 //! ```
 //!
 //! If you have a nightly compiler you can append `--features lints` to both commands

src/macros.rs

@@ -416,9 +416,9 @@ macro_rules! crate_authors {
     };
 }
 
-/// App, Arg, SubCommand and Group builder macro (Usage-string like input) must be compiled with
-/// the `unstable` feature in order to use.
-#[cfg_attr(feature = "unstable", macro_export)]
+/// Build `App`, `Arg`s, `SubCommand`s and `Group`s with Usage-string like input
+/// but without the parsing.
+#[macro_export]
 macro_rules! clap_app {
     (@app ($builder:expr)) => { $builder };
     (@app ($builder:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => {