docs(Default Values): adds better examples on using default values

Closes #418

examples/10_default_values.rs

@@ -3,19 +3,38 @@ extern crate clap;
 use clap::{App, Arg};
 
 fn main() {
-    // You can get a "default value" like feature by using Option<T>'s .unwrap_or() method
+    // There are two ways in which to get a default value, one is to use claps Arg::default_value
+    // method, and the other is to use Rust's built in Option::unwrap_or method.
     //
-    // Let's assume you have -c <config> argument to allow users to specify a configuration file
-    // but you also want to support a default file, if none is specified.
+    // I'll demo both here.
+    //
+    // First, we'll use clap's Arg::default_value with an "INPUT" file.
     let matches = App::new("myapp").about("does awesome things")
+                        .arg(Arg::with_name("INPUT")
+                                .help("The input file to use") // Note, we don't need to specify
+                                                               // anything like, "Defaults to..."
+                                                               // because clap will automatically
+                                                               // generate that for us, and place
+                                                               // it in the help text
+                                .default_value("input.txt")
+                                .index(1))
+
+                        // Next we'll use the Option::unwrap_or method on this "CONFIG" option
                         .arg(Arg::with_name("CONFIG")
+                                // Note that we have to manaully include some verbage to the user
+                                // telling them what the default will be.
                                 .help("The config file to use (default is \"config.json\")")
                                 .short("c")
                                 .takes_value(true))
                         .get_matches();
 
+    // It's safe to call unwrap because the value with either be what the user input at runtime
+    // or "input.txt"
+    let input = matches.value_of("INPUT").unwrap();
+
+    // Using Option::unwrap_or we get the same affect, but without the added help text injection
     let config_file = matches.value_of("CONFIG").unwrap_or("config.json");
 
-    // If the user passed in a -c <file> we'll see that value, if not we'll see 'config.json'
+    println!("The input file is: {}", input);
     println!("The config file is: {}", config_file);
-}
+}

src/args/arg.rs

@@ -2186,6 +2186,8 @@ impl<'a, 'b> Arg<'a, 'b> {
     ///
     /// # Examples
     ///
+    /// First we use the default value without providing any value at runtime.
+    ///
     /// ```rust
     /// # use clap::{App, Arg};
     /// let m = App::new("defvals")
@@ -2200,6 +2202,23 @@ impl<'a, 'b> Arg<'a, 'b> {
     /// assert!(m.is_present("opt"));
     /// assert_eq!(m.occurrences_of("opt"), 0);
     /// ```
+    ///
+    /// Next we provide a valu at runtime to override the default.
+    ///
+    /// ```rust
+    /// # use clap::{App, Arg};
+    /// let m = App::new("defvals")
+    ///     .arg(Arg::with_name("opt")
+    ///         .long("myopt")
+    ///         .default_value("myval"))
+    ///     .get_matches_from(vec![
+    ///         "defvals", "--myopt=non_default"
+    ///     ]);
+    ///
+    /// assert_eq!(m.value_of("opt"), Some("non_default"));
+    /// assert!(m.is_present("opt"));
+    /// assert_eq!(m.occurrences_of("opt"), 1);
+    /// ```
     /// [`ArgMatches::occurrences_of`]: /struct.ArgMatches.html#method.occurrences_of
     /// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
     /// [`Arg::takes_value(true)`]: /struct.Arg.html#method.takes_value