Auto merge of #682 - tormol:ignore_less_doctests, r=kbknapp

Ignore fewer doc-tests

.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.)

.travis.yml

@@ -14,10 +14,9 @@ before_script:
     export PATH=$HOME/.local/bin:$PATH
 script:
   - |
-    cargo build --verbose --no-default-features &&
-    cargo build --verbose --features yaml &&
-    cargo test --verbose --features yaml &&
-    travis-cargo --only nightly build -- --features travis &&
+    travis-cargo test -- --verbose --no-default-features &&
+    travis-cargo --skip nightly test -- --verbose --features "yaml unstable" &&
+    travis-cargo --only nightly test -- --verbose --features "yaml unstable nightly" &&
     travis-cargo --only nightly bench
 addons:
   apt:
@@ -27,8 +26,8 @@ addons:
     - libdw-dev
 after_success:
   - |
-    travis-cargo --only stable coveralls --no-sudo -- --features yaml
+    travis-cargo --only stable coveralls --no-sudo -- --features "yaml unstable"
 env:
   global:
-    - TRAVIS_CARGO_NIGHTLY_FEATURE=travis
+    - TRAVIS_CARGO_NIGHTLY_FEATURE=lints
     - secure: JLBlgHY6OEmhJ8woewNJHmuBokTNUv7/WvLkJGV8xk0t6bXBwSU0jNloXwlH7FiQTc4TccX0PumPDD4MrMgxIAVFPmmmlQOCmdpYP4tqZJ8xo189E5zk8lKF5OyaVYCs5SMmFC3cxCsKjfwGIexNu3ck5Uhwe9jI0tqgkgM3URA=

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,13 +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"]
-lints       = ["clippy", "nightly"]
-nightly     = [] # for building with nightly and unstable features
-unstable    = [] # for building with unstable features on stable Rust
-debug       = [] # for building with debug messages
-travis      = ["lints", "nightly"] # for building with travis-cargo
+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
+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/app/mod.rs

@@ -130,11 +130,15 @@ impl<'a, 'b> App<'a, 'b> {
     /// of an [`App`] struct.
     ///
     /// ```ignore
+    /// # #[macro_use]
+    /// # extern crate clap;
     /// # use clap::App;
+    /// # fn main() {
     /// let yml = load_yaml!("app.yml");
     /// let app = App::from_yaml(yml);
     ///
     /// // continued logic goes here, such as `app.get_matches()` etc.
+    /// # }
     /// ```
     /// [`App`]: ./struct.App.html
     /// [`examples/17_yaml.rs`]: https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.rs
@@ -966,7 +970,7 @@ impl<'a, 'b> App<'a, 'b> {
     ///
     /// The above example displays the following help message
     ///
-    /// ```ignore
+    /// ```text
     /// cust-ord
     ///
     /// USAGE:
@@ -1051,7 +1055,7 @@ impl<'a, 'b> App<'a, 'b> {
     /// First, it helps if we separate out our `App` definition into a seperate file. Whether you
     /// do this as a function, or bare App definition is a matter of personal preference.
     ///
-    /// ```ignore
+    /// ```
     /// // src/cli.rs
     ///
     /// use clap::{App, Arg, SubCommand};
@@ -1087,7 +1091,7 @@ impl<'a, 'b> App<'a, 'b> {
     ///
     /// Next, we set up our `Cargo.toml` to use a `build.rs` build script.
     ///
-    /// ```ignore
+    /// ```toml
     /// # Cargo.toml
     /// build = "build.rs"
     ///

src/app/parser.rs

@@ -229,7 +229,7 @@ impl<'a, 'b> Parser<'a, 'b>
 
     pub fn add_subcommand(&mut self, mut subcmd: App<'a, 'b>) {
         debugln!("fn=Parser::add_subcommand;");
-        debugln!("Term widnth...{:?}", self.meta.term_w);
+        debugln!("Term width...{:?}", self.meta.term_w);
         subcmd.p.meta.term_w = self.meta.term_w;
         debug!("Is help...");
         if subcmd.p.meta.name == "help" {