From 4ee85b95d2d16708a016a3ba4e6e2c93b89b7fad Mon Sep 17 00:00:00 2001 From: tormol Date: Sat, 15 Oct 2016 04:58:36 +0200 Subject: [PATCH] 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 | 2 +- Cargo.toml | 22 +++++++-------- README.md | 59 ++++++++++++++++++++++----------------- src/lib.rs | 62 ++++++++++++++++++++++++----------------- 4 files changed, 81 insertions(+), 64 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fa927520c16..7a122363139 100644 --- a/.github/CONTRIBUTING.md +++ b/.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.) diff --git a/Cargo.toml b/Cargo.toml index 6684ae4d75a..d3f17bb2ecd 100644 --- a/Cargo.toml +++ b/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 diff --git a/README.md b/README.md index 4f2d7c72c2a..7c6491894a1 100644 --- a/README.md +++ b/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 diff --git a/src/lib.rs b/src/lib.rs index 12845120c8e..637481e33db 100644 --- a/src/lib.rs +++ b/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.