docs: Encourage multiple_occurrences

There were fewer occasions than I expected where the use of
`multiple_values` was superfluous and we could instead use the more
predictable `multiple_occurrences`.

In terms of the remaining `multiple` split work, #1772 will take care of the derive
behavior and #2692 will resolve any remaining issues with values vs
occurrences in positional arguments.

Fixes #2816

examples/17_yaml.yaml

@@ -16,7 +16,7 @@ args:
         about: example option argument from yaml
         short: o
         long: option
-        multiple_values: true
+        multiple_occurrences: true
         takes_value: true
     - pos:
         about: example positional argument from yaml
@@ -28,7 +28,7 @@ args:
     - flag:
         about: demo flag argument
         short: F
-        multiple_values: true
+        multiple_occurrences: true
         takes_value: true
         global: true
         # Conflicts, mutual overrides, and requirements can all be defined as a
@@ -76,7 +76,7 @@ subcommands:
         args:
             - scopt:
                 short: B
-                multiple_values: true
+                multiple_occurrences: true
                 about: example subcommand option
                 takes_value: true
             - scpos1:

examples/20_subcommands.rs

@@ -79,7 +79,7 @@ fn main() {
                         .long("stuff")
                         .about("Stuff to add")
                         .takes_value(true)
-                        .multiple_values(true),
+                        .multiple_occurrences(true),
                 ),
         )
         .get_matches();

src/parse/matches/arg_matches.rs

@@ -224,11 +224,11 @@ impl ArgMatches {
     /// # use clap::{App, Arg};
     /// let m = App::new("myprog")
     ///     .arg(Arg::new("output")
-    ///         .multiple_values(true)
+    ///         .multiple_occurrences(true)
     ///         .short('o')
     ///         .takes_value(true))
     ///     .get_matches_from(vec![
-    ///         "myprog", "-o", "val1", "val2", "val3"
+    ///         "myprog", "-o", "val1", "-o", "val2", "-o", "val3"
     ///     ]);
     /// let vals: Vec<&str> = m.values_of("output").unwrap().collect();
     /// assert_eq!(vals, ["val1", "val2", "val3"]);
@@ -981,9 +981,9 @@ impl ArgMatches {
 /// let m = App::new("myapp")
 ///     .arg(Arg::new("output")
 ///         .short('o')
-///         .multiple_values(true)
+///         .multiple_occurrences(true)
 ///         .takes_value(true))
-///     .get_matches_from(vec!["myapp", "-o", "val1", "val2"]);
+///     .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]);
 ///
 /// let mut values = m.values_of("output").unwrap();
 ///