docs(tutorial): Encourage App::debug_assert

CHANGELOG.md

@@ -69,7 +69,7 @@ fn app() -> clap::App<'static> {
 
 #[test]
 fn verify_app() {
-    app.debug_assert();
+    app().debug_assert();
 }
 ```
 

Cargo.toml

@@ -250,6 +250,12 @@ name = "04_04_custom"
 path = "examples/tutorial_builder/04_04_custom.rs"
 required-features = ["cargo"]
 
+[[example]]
+name = "05_01_assert"
+path = "examples/tutorial_builder/05_01_assert.rs"
+required-features = ["cargo"]
+test = true
+
 [[example]]
 name = "01_quick_derive"
 path = "examples/tutorial_derive/01_quick.rs"
@@ -320,6 +326,12 @@ name = "04_04_custom_derive"
 path = "examples/tutorial_derive/04_04_custom.rs"
 required-features = ["derive"]
 
+[[example]]
+name = "05_01_assert_derive"
+path = "examples/tutorial_derive/05_01_assert.rs"
+required-features = ["derive"]
+test = true
+
 [[example]]
 name = "custom-bool"
 path = "examples/derive_ref/custom-bool.rs"

examples/tutorial_builder/05_01_assert.rs

@@ -0,0 +1,24 @@
+use clap::{app_from_crate, arg};
+
+fn main() {
+    let matches = app().get_matches();
+
+    // Note, it's safe to call unwrap() because the arg is required
+    let port: usize = matches
+        .value_of_t("PORT")
+        .expect("'PORT' is required and parsing will fail if its missing");
+    println!("PORT = {}", port);
+}
+
+fn app() -> clap::App<'static> {
+    app_from_crate!().arg(
+        arg!(<PORT>)
+            .help("Network port to use")
+            .validator(|s| s.parse::<usize>()),
+    )
+}
+
+#[test]
+fn verify_app() {
+    app().debug_assert();
+}

examples/tutorial_builder/README.md

@@ -15,7 +15,8 @@
     2. [Validated values](#validated-values)
     3. [Argument Relations](#relations-relations)
     4. [Custom Validation](#custom-validation)
-5. [Contributing](#contributing)
+5. [Tips](#tips)
+6. [Contributing](#contributing)
 
 ## Quick Start
 
@@ -549,6 +550,10 @@ Version: 2.2.3
 Doing work using input input.txt and config config.toml
 ```
 
+## Tips
+
+- Proactively check for bad `App` configurations by calling `App::debug_assert` ([example](05_01_assert.rs))
+
 ## Contributing
 
 New example code:

examples/tutorial_derive/05_01_assert.rs

@@ -0,0 +1,21 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[clap(author, version, about)]
+struct Cli {
+    /// Network port to use
+    #[clap(parse(try_from_str))]
+    port: usize,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("PORT = {}", cli.port);
+}
+
+#[test]
+fn verify_app() {
+    use clap::IntoApp;
+    Cli::into_app().debug_assert()
+}

examples/tutorial_derive/README.md

@@ -15,7 +15,8 @@
     2. [Validated values](#validated-values)
     3. [Argument Relations](#relations-relations)
     4. [Custom Validation](#custom-validation)
-5. [Contributing](#contributing)
+5. [Tips](#tips)
+6. [Contributing](#contributing)
 
 ## Quick Start
 
@@ -517,6 +518,10 @@ Version: 2.2.3
 Doing work using input input.txt and config config.toml
 ```
 
+## Tips
+
+- Proactively check for bad `App` configurations by calling `App::debug_assert` ([example](05_01_assert.rs))
+
 ## Contributing
 
 New example code: