fix(app): Rename generaet_usage to render_usage

This is inline with all of our other help-related functions that return
strings.

This is a part of #2164

BREAKING CHANEG: `App::generate_usage` (added in v3) ->
`App::render_usage`.

src/build/app/mod.rs

@@ -1920,8 +1920,17 @@ impl<'help> App<'help> {
         self._render_version(true)
     }
 
-    /// @TODO-v3-alpha @docs @p2: write docs
-    pub fn generate_usage(&mut self) -> String {
+    /// Returns the usage statement
+    ///
+    /// ### Examples
+    ///
+    /// ```rust
+    /// # use clap::App;
+    /// use std::io;
+    /// let mut app = App::new("myprog");
+    /// println!("{}", app.render_usage());
+    /// ```
+    pub fn render_usage(&mut self) -> String {
         // If there are global arguments, or settings we need to propagate them down to subcommands
         // before parsing incase we run into a subcommand
         self._build();

tests/positionals.rs

@@ -189,13 +189,13 @@ fn positional_hyphen_does_not_panic() {
 #[test]
 fn single_positional_usage_string() {
     let mut app = App::new("test").arg("[FILE] 'some file'");
-    assert_eq!(app.generate_usage(), "USAGE:\n    test [FILE]");
+    assert_eq!(app.render_usage(), "USAGE:\n    test [FILE]");
 }
 
 #[test]
 fn single_positional_multiple_usage_string() {
     let mut app = App::new("test").arg("[FILE]... 'some file'");
-    assert_eq!(app.generate_usage(), "USAGE:\n    test [FILE]...");
+    assert_eq!(app.render_usage(), "USAGE:\n    test [FILE]...");
 }
 
 #[test]
@@ -203,7 +203,7 @@ fn multiple_positional_usage_string() {
     let mut app = App::new("test")
         .arg("[FILE] 'some file'")
         .arg("[FILES]... 'some file'");
-    assert_eq!(app.generate_usage(), "USAGE:\n    test [ARGS]");
+    assert_eq!(app.render_usage(), "USAGE:\n    test [ARGS]");
 }
 
 #[test]
@@ -211,13 +211,13 @@ fn multiple_positional_one_required_usage_string() {
     let mut app = App::new("test")
         .arg("<FILE> 'some file'")
         .arg("[FILES]... 'some file'");
-    assert_eq!(app.generate_usage(), "USAGE:\n    test <FILE> [FILES]...");
+    assert_eq!(app.render_usage(), "USAGE:\n    test <FILE> [FILES]...");
 }
 
 #[test]
 fn single_positional_required_usage_string() {
     let mut app = App::new("test").arg("<FILE> 'some file'");
-    assert_eq!(app.generate_usage(), "USAGE:\n    test <FILE>");
+    assert_eq!(app.render_usage(), "USAGE:\n    test <FILE>");
 }
 
 // This tests a programmer error and will only succeed with debug_assertions

tests/subcommands.rs

@@ -423,10 +423,7 @@ fn subcommand_placeholder_test() {
         .subcommand(App::new("subcommand"))
         .subcommand_placeholder("TEST_PLACEHOLDER", "TEST_HEADER");
 
-    assert_eq!(
-        &app.generate_usage(),
-        "USAGE:\n    myprog [TEST_PLACEHOLDER]"
-    );
+    assert_eq!(&app.render_usage(), "USAGE:\n    myprog [TEST_PLACEHOLDER]");
 
     let mut help_text = Vec::new();
     app.write_help(&mut help_text)