docs: Improve documentation around features

* Clap has dependencies even with all features disabled.
* The "nightly" feature does nothing, so don't mention it.
* Explain the difference between "unstable" and "nightly" better.
* Split features into groups (default, opt-in, clap-development).
* For contributors: update what tests should be run, and remove make command.
* Removes a repeated word and splits up some long markdown lines.

Also groups features by category and dependencies by feature in Cargo.toml.

.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 --features yaml && make -C clap-tests test`)
+5. Run the tests (`cargo test --no-std-features && cargo test --features="yaml unstable"`)
 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

@@ -15,16 +15,16 @@ A simple to use, efficient, and full featured  Command Line Argument Parser
 """
 
 [dependencies]
-bitflags  = "~0.7"
-vec_map   = "~0.6"
-libc      = { version = "~0.2.9",  optional = true }
-ansi_term = { version = "~0.9.0",  optional = true }
+bitflags              = "~0.7"
+vec_map               = "~0.6"
+unicode-width         = "~0.1.3"
+unicode-segmentation  = "~0.1.2"
 strsim    = { version = "~0.5.1",  optional = true }
+ansi_term = { version = "~0.9.0",  optional = true }
+term_size = { version = "~0.2.0",  optional = true }
+libc      = { version = "~0.2.9",  optional = true }
 yaml-rust = { version = "~0.3.2",  optional = true }
 clippy    = { version = "~0.0.88", optional = true }
-unicode-width = "~0.1.3"
-unicode-segmentation = "~0.1.2"
-term_size = { version = "~0.2.0", optional = true }
 
 [dev-dependencies]
 regex = "~0.1.69"
@@ -33,12 +33,12 @@ regex = "~0.1.69"
 default     = ["suggestions", "color", "wrap_help"]
 suggestions = ["strsim"]
 color       = ["ansi_term", "libc"]
-yaml        = ["yaml-rust"]
 wrap_help   = ["libc", "term_size"]
+yaml        = ["yaml-rust"]
+unstable    = [] # for building with unstable clap features (doesn't require nightly Rust)
+nightly     = [] # for building with unstable Rust features (currently none)
 lints       = ["clippy"] # Requires nightly Rust
-nightly     = [] # for building with nightly and unstable features
-unstable    = [] # for building with unstable features on stable Rust
-debug       = [] # for building with debug messages
+debug       = [] # Enables debug messages
 
 [profile.release]
 opt-level = 3

README.md

@@ -432,8 +432,8 @@ The following example is functionally the same as the one above, but shows a far
 ```rust
 // (Full example with detailed comments in examples/01a_quick_example.rs)
 //
-// This example demonstrates clap's "usage strings" method of creating arguments which is less
-// less verbose
+// This example demonstrates clap's "usage strings" method of creating arguments
+// which is less verbose
 extern crate clap;
 use clap::{Arg, App, SubCommand};
 
@@ -457,7 +457,10 @@ fn main() {
 }
 ```
 
-This final method shows how you can use a YAML file to build your CLI and keep your Rust source tidy or support multiple localized translations by having different YAML files for each localization. First, create the `cli.yml` file to hold your CLI options, but it could be called anything we like (we'll use the same both examples above to keep it functionally equivalent):
+This final method shows how you can use a YAML file to build your CLI and keep your Rust source tidy
+or support multiple localized translations by having different YAML files for each localization.
+First, create the `cli.yml` file to hold your CLI options, but it could be called anything we like
+(we'll use the same both examples above to keep it functionally equivalent):
 
 ```yaml
 name: myapp
@@ -581,11 +584,12 @@ fn main() {
 
 For full usage, add `clap` as a dependency in your `Cargo.toml` file to use from crates.io:
 
- ```toml
- [dependencies]
- clap = "2"
- ```
- Or track the latest on the master branch at github:
+```toml
+[dependencies]
+clap = "2"
+```
+
+Or get the latest changes from the master branch at github:
 
 ```toml
 [dependencies.clap]
@@ -600,7 +604,13 @@ Then run `cargo build` or `cargo update && cargo build` for your project.
 
 ### Optional Dependencies / Features
 
-If you'd like to keep your dependency list to **only** `clap`, you can disable any features that require an additional dependency. To do this, add this to your `Cargo.toml`:
+#### Features enabled by default
+
+* **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos. (builds dependency `strsim`)
+* **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs. (builds dependency `ansi-term` and `libc`)
+* **"wrap_help"**: Wraps the help at the actual terminal width when available, instead of 120 chracters. (builds dependency `term_size`, and `libc`)
+
+To disable these, add this to your `Cargo.toml`:
 
 ```toml
 [dependencies.clap]
@@ -618,15 +628,11 @@ default-features = false
 # Cherry-pick the features you'd like to use
 features = [ "suggestions", "color" ]
 ```
-The following is a list of optional `clap` features:
 
-* **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos. (builds dependency `strsim`)
-* **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs. (builds dependency `ansi-term` and `libc`)
-* **"wrap_help"**: Automatically detects terminal width and wraps long help text lines with proper indentation alignment (builds dependency `libc`, and `term_size`)
-* **"lints"**: This is **not** included by default and should only be used while developing to run basic lints against changes. This can only be used on Rust nightly. (builds dependency `clippy`)
-* **"debug"**: This is **not** included by default and should only be used while developing to display debugging information.
-* **"yaml"**: This is **not** included by default. Enables building CLIs from YAML documents. (builds dependency `yaml-rust`)
-* **"unstable"**: This is **not** included by default. Enables unstable features, unstable refers to whether or not they may change, not performance stability.
+#### 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
 
@@ -657,19 +663,20 @@ Another really great way to help is if you find an interesting, or helpful way i
 
 Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before you start contributing.
 
-### Running the tests
-
-If contributing, you can run the tests as follows (assuming you're in the `clap-rs` directory)
+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
 
-# If your tests affect the YAML feature set
-$ cargo test --features yaml
+If you have a nightly compiler you can append `--features lints` to both commands
+to get style warnings and code smells; If you get one from code you think is fine,
+you can ignore it by prepending `#[cfg_attr(feature="lints", allow(lint_name))]`
+to the function or impl block.
 
-# Only on nightly compiler:
-$ cargo build --features lints
-```
+If you are debugging (or just trying to understand the code) you can enable the
+"debug" feature which will trace function calls and brances in some parts of the code.
 
 ### Goals
 

src/lib.rs

@@ -117,13 +117,15 @@
 //! }
 //! ```
 //!
-//! The following example is functionally the same as the one above, but shows a far less verbose method but sacrifices some of the advanced configuration options (not shown in this small example).
+//! The following example is functionally the same as the one above,
+//! but shows a far less verbose method but sacrifices some of the advanced configuration options
+//! (not shown in this small example).
 //!
 //! ```no_run
 //! // (Full example with detailed comments in examples/01a_quick_example.rs)
 //! //
-//! // This example demonstrates clap's "usage strings" method of creating arguments which is less
-//! // less verbose
+//! // This example demonstrates clap's "usage strings" method of creating arguments
+//! // which is less verbose
 //! extern crate clap;
 //! use clap::{Arg, App, SubCommand};
 //!
@@ -152,10 +154,10 @@
 #![cfg_attr(not(feature="unstable"), doc=" ```ignore")]
 #![cfg_attr(    feature="unstable" , doc=" ```no_run")]
 //! // (Full example with detailed comments in examples/01c_quick_example.rs)
-//! // Must be compiled with `--features unstable`
+//! // 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
+//! // This example demonstrates clap's "usage strings" method of creating arguments
+//! // which is less less verbose
 //! #[macro_use]
 //! extern crate clap;
 //!
@@ -303,11 +305,12 @@
 //!
 //! For full usage, add `clap` as a dependency in your `Cargo.toml` file to use from crates.io:
 //!
-//!  ```toml
-//!  [dependencies]
-//!  clap = "2"
-//!  ```
-//!  Or track the latest on the master branch at github:
+//! ```toml
+//! [dependencies]
+//! clap = "2"
+//! ```
+//!
+//! Or get the latest changes from the master branch at github:
 //!
 //! ```toml
 //! [dependencies.clap]
@@ -322,7 +325,13 @@
 //!
 //! ### Optional Dependencies / Features
 //!
-//! If you'd like to keep your dependency list to **only** `clap`, you can disable any features that require an additional dependency. To do this, add this to your `Cargo.toml`:
+//! #### Features enabled by default
+//!
+//! * **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos.
+//! * **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs.
+//! * **"wrap_help"**: Wraps the help at the actual terminal width when available, instead of 120 chracters.
+//!
+//! To disable these, add this to your `Cargo.toml`:
 //!
 //! ```toml
 //! [dependencies.clap]
@@ -341,14 +350,10 @@
 //! features = [ "suggestions", "color" ]
 //! ```
 //!
-//! The following is a list of optional `clap` features:
+//! #### Opt-in features
 //!
-//! * **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos.
-//! * **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs.
-//! * **"lints"**: This is **not** included by default and should only be used while developing to run basic lints against changes. This can only be used on Rust nightly.
-//! * **"debug"**: This is **not** included by default and should only be used while developing to display debugging information.
-//! * **"yaml"**: This is **not** included by default. Enables building CLIs from YAML documents.
-//! * **"unstable"**: This is **not** included by default. Enables unstable features, unstable refers to whether or not they may change, not performance stability.
+//! * **"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
 //!
@@ -364,18 +369,23 @@
 //!
 //! *Note*: Apologies for the resolution of the first video, it will be updated to a better resolution soon. The other videos have a proper resolution.
 //!
-//! ### Running the tests
+//! ### For clap contributors
 //!
-//! If contributing, you can run the tests as follows (assuming you're in the `clap-rs` directory)
+//! If contributing, you can run theese commands to test everything:
 //!
 //! ```sh
-//! $ cargo test && make -C clap-tests test
-//! $ cargo test --features yaml
-//!
-//! # Only on nightly compiler:
-//! $ cargo build --features lints
+//! $ cargo test --no-default-features
+//! $ cargo test --features "yaml unstable"
 //! ```
 //!
+//! If you have a nightly compiler you can append `--features lints` to both commands
+//! to get style warnings and code smells; If you get one from code you think is fine,
+//! you can ignore it by prepending `#[cfg_attr(feature="lints", allow(lint_name))]`
+//! to the function or impl block.
+//!
+//! If you are debugging (or just trying to understand the code) you can enable the
+//! "debug" feature which will trace function calls and brances in some parts of the code.
+//!
 //! ## License
 //!
 //! `clap` is licensed under the MIT license. Please read the [LICENSE-MIT](LICENSE-MIT) file in this repository for more information.