From fd8c9ce7958a25c26f9243b583422a358c7d26da Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Tue, 13 Apr 2021 18:12:39 -0700
Subject: [PATCH] Use launch-inferred '_' in most example code.

---
 README.md                                     |  2 +-
 contrib/lib/src/databases/mod.rs              |  2 +-
 contrib/lib/src/serve.rs                      | 10 +++----
 core/codegen/tests/async-entry.rs             |  2 +-
 .../tests/ui-fail-nightly/async-entry.stderr  |  2 +-
 .../tests/ui-fail-stable/async-entry.stderr   |  2 +-
 core/codegen/tests/ui-fail/async-entry.rs     |  4 +--
 core/lib/src/fairing/ad_hoc.rs                |  5 +++-
 core/lib/src/local/asynchronous/response.rs   |  2 +-
 core/lib/src/local/blocking/response.rs       |  2 +-
 core/lib/src/local/mod.rs                     |  3 +--
 core/lib/src/rocket.rs                        | 27 ++++++++++---------
 core/lib/src/state.rs                         |  2 +-
 examples/todo/src/main.rs                     |  2 +-
 site/guide/10-pastebin.md                     |  8 +++---
 site/guide/2-getting-started.md               |  2 +-
 site/guide/3-overview.md                      | 12 ++++-----
 site/guide/4-requests.md                      |  2 +-
 site/guide/6-state.md                         |  2 +-
 site/guide/7-fairings.md                      |  2 +-
 site/guide/8-testing.md                       |  8 +++---
 21 files changed, 54 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 528bbc91..de97387e 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ fn hello(name: &str, age: u8) -> String {
 }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/hello", routes![hello])
 }
 ```
diff --git a/contrib/lib/src/databases/mod.rs b/contrib/lib/src/databases/mod.rs
index 2bb3f150..7abfb42d 100644
--- a/contrib/lib/src/databases/mod.rs
+++ b/contrib/lib/src/databases/mod.rs
@@ -63,7 +63,7 @@
 //! struct LogsDbConn(diesel::SqliteConnection);
 //!
 //! #[launch]
-//! fn rocket() -> rocket::Rocket {
+//! fn rocket() -> _ {
 //!     rocket::build().attach(LogsDbConn::fairing())
 //! }
 //! # } fn main() {}
diff --git a/contrib/lib/src/serve.rs b/contrib/lib/src/serve.rs
index 5544e2b1..d3a083dc 100644
--- a/contrib/lib/src/serve.rs
+++ b/contrib/lib/src/serve.rs
@@ -203,7 +203,7 @@ impl std::ops::BitOr for Options {
 /// use rocket_contrib::serve::StaticFiles;
 ///
 /// #[launch]
-/// fn rocket() -> rocket::Rocket {
+/// fn rocket() -> _ {
 ///     rocket::build().mount("/public", StaticFiles::from("/static"))
 /// }
 /// ```
@@ -227,7 +227,7 @@ impl std::ops::BitOr for Options {
 /// use rocket_contrib::serve::{StaticFiles, crate_relative};
 ///
 /// #[launch]
-/// fn rocket() -> rocket::Rocket {
+/// fn rocket() -> _ {
 ///     rocket::build().mount("/", StaticFiles::from(crate_relative!("static")))
 /// }
 /// ```
@@ -263,7 +263,7 @@ impl StaticFiles {
     /// use rocket_contrib::serve::StaticFiles;
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build().mount("/static", StaticFiles::from("/www/public"))
     /// }
     /// ```
@@ -276,7 +276,7 @@ impl StaticFiles {
     /// use rocket_contrib::serve::StaticFiles;
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build().mount("/static", StaticFiles::from("/www/public").rank(30))
     /// }
     /// ```
@@ -305,7 +305,7 @@ impl StaticFiles {
     /// use rocket_contrib::serve::{StaticFiles, Options};
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     let options = Options::Index | Options::DotFiles;
     ///     rocket::build()
     ///         .mount("/static", StaticFiles::from("/www/public"))
diff --git a/core/codegen/tests/async-entry.rs b/core/codegen/tests/async-entry.rs
index 6ff8dedb..09adc38b 100644
--- a/core/codegen/tests/async-entry.rs
+++ b/core/codegen/tests/async-entry.rs
@@ -37,7 +37,7 @@ mod b_inferred {
 mod c {
     // non-async launch.
     #[rocket::launch]
-    fn rocket() -> rocket::Rocket {
+    fn rocket() -> _ {
         rocket::build()
     }
 
diff --git a/core/codegen/tests/ui-fail-nightly/async-entry.stderr b/core/codegen/tests/ui-fail-nightly/async-entry.stderr
index 73384ca0..5dc07daf 100644
--- a/core/codegen/tests/ui-fail-nightly/async-entry.stderr
+++ b/core/codegen/tests/ui-fail-nightly/async-entry.stderr
@@ -108,7 +108,7 @@ note: this function cannot be `main`
 error[E0728]: `await` is only allowed inside `async` functions and blocks
   --> $DIR/async-entry.rs:75:17
    |
-74 |     fn rocket() -> rocket::Rocket {
+72 |     fn rocket() -> _ {
    |        ------ this is not `async`
 75 |         let _ = rocket::build().launch().await;
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only allowed inside `async` functions and blocks
diff --git a/core/codegen/tests/ui-fail-stable/async-entry.stderr b/core/codegen/tests/ui-fail-stable/async-entry.stderr
index 171eba60..201f4100 100644
--- a/core/codegen/tests/ui-fail-stable/async-entry.stderr
+++ b/core/codegen/tests/ui-fail-stable/async-entry.stderr
@@ -102,7 +102,7 @@ error: [note] this function cannot be `main`
 error[E0728]: `await` is only allowed inside `async` functions and blocks
   --> $DIR/async-entry.rs:75:17
    |
-74 |     fn rocket() -> rocket::Rocket {
+72 |     fn rocket() -> _ {
    |        ------ this is not `async`
 75 |         let _ = rocket::build().launch().await;
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ only allowed inside `async` functions and blocks
diff --git a/core/codegen/tests/ui-fail/async-entry.rs b/core/codegen/tests/ui-fail/async-entry.rs
index 45ad3ee9..52f5c0e8 100644
--- a/core/codegen/tests/ui-fail/async-entry.rs
+++ b/core/codegen/tests/ui-fail/async-entry.rs
@@ -41,7 +41,7 @@ mod launch_a {
 
 mod launch_b {
     #[rocket::launch]
-    async fn rocket() -> rocket::Rocket {
+    async fn rocket() -> _ {
         let _ = rocket::build().launch().await;
         "hi".to_string()
     }
@@ -71,7 +71,7 @@ mod launch_e {
 
 mod launch_f {
     #[rocket::launch]
-    fn rocket() -> rocket::Rocket {
+    fn rocket() -> _ {
         let _ = rocket::build().launch().await;
         rocket::build()
     }
diff --git a/core/lib/src/fairing/ad_hoc.rs b/core/lib/src/fairing/ad_hoc.rs
index b9da0680..c7debe3c 100644
--- a/core/lib/src/fairing/ad_hoc.rs
+++ b/core/lib/src/fairing/ad_hoc.rs
@@ -200,7 +200,10 @@ impl AdHoc {
     ///     /* and so on.. */
     /// }
     ///
-    /// let fairing = AdHoc::config::<Config>();
+    /// #[launch]
+    /// fn rocket() -> _ {
+    ///     rocket::build().attach(AdHoc::config::<Config>())
+    /// }
     /// ```
     pub fn config<'de, T>() -> AdHoc
         where T: serde::Deserialize<'de> + Send + Sync + 'static
diff --git a/core/lib/src/local/asynchronous/response.rs b/core/lib/src/local/asynchronous/response.rs
index 467aa5c5..41377485 100644
--- a/core/lib/src/local/asynchronous/response.rs
+++ b/core/lib/src/local/asynchronous/response.rs
@@ -28,7 +28,7 @@ use crate::{Request, Response};
 /// }
 ///
 /// #[launch]
-/// fn rocket() -> rocket::Rocket {
+/// fn rocket() -> _ {
 ///     rocket::build().mount("/", routes![hello_world])
 ///     #    .reconfigure(rocket::Config::debug_default())
 /// }
diff --git a/core/lib/src/local/blocking/response.rs b/core/lib/src/local/blocking/response.rs
index 5b706ffd..be1abf50 100644
--- a/core/lib/src/local/blocking/response.rs
+++ b/core/lib/src/local/blocking/response.rs
@@ -25,7 +25,7 @@ use super::Client;
 /// }
 ///
 /// #[launch]
-/// fn rocket() -> rocket::Rocket {
+/// fn rocket() -> _ {
 ///     rocket::build().mount("/", routes![hello_world])
 ///     #    .reconfigure(rocket::Config::debug_default())
 /// }
diff --git a/core/lib/src/local/mod.rs b/core/lib/src/local/mod.rs
index f969d4db..6afbf04f 100644
--- a/core/lib/src/local/mod.rs
+++ b/core/lib/src/local/mod.rs
@@ -43,8 +43,7 @@
 //!
 //! # /*
 //! #[launch]
-//! # */
-//! fn rocket() -> rocket::Rocket {
+//! fn rocket() -> _ {
 //!     rocket::build().mount("/", routes![hello])
 //! }
 //!
diff --git a/core/lib/src/rocket.rs b/core/lib/src/rocket.rs
index 1419d71e..84a16311 100644
--- a/core/lib/src/rocket.rs
+++ b/core/lib/src/rocket.rs
@@ -47,9 +47,11 @@ impl Rocket {
     /// # Examples
     ///
     /// ```rust
-    /// # {
-    /// rocket::build()
-    /// # };
+    /// # use rocket::launch;
+    /// #[launch]
+    /// fn rocket() -> _ {
+    ///     rocket::build()
+    /// }
     /// ```
     #[track_caller]
     #[inline(always)]
@@ -177,7 +179,7 @@ impl Rocket {
     /// }
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build().mount("/hello", routes![hi])
     /// }
     /// ```
@@ -195,10 +197,11 @@ impl Rocket {
     ///     Outcome::from(req, "Hello!").pin()
     /// }
     ///
-    /// # let _ = async { // We don't actually want to launch the server in an example.
-    /// rocket::build().mount("/hello", vec![Route::new(Get, "/world", hi)])
-    /// #     .launch().await;
-    /// # };
+    /// #[launch]
+    /// fn rocket() -> _ {
+    ///     let hi_route = Route::new(Method::Get, "/world", hi);
+    ///     rocket::build().mount("/hello", vec![hi_route])
+    /// }
     /// ```
     pub fn mount<'a, B, R>(mut self, base: B, routes: R) -> Self
         where B: TryInto<Origin<'a>> + Clone + Display,
@@ -263,7 +266,7 @@ impl Rocket {
     /// }
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build().register("/", catchers![internal_error, not_found])
     /// }
     /// ```
@@ -322,7 +325,7 @@ impl Rocket {
     /// }
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build()
     ///         .mount("/", routes![index])
     ///         .manage(MyValue(10))
@@ -350,7 +353,7 @@ impl Rocket {
     /// use rocket::fairing::AdHoc;
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build()
     ///         .attach(AdHoc::on_liftoff("Liftoff Message", |_| Box::pin(async {
     ///             println!("We have liftoff!");
@@ -372,7 +375,7 @@ impl Rocket {
     /// use rocket::fairing::AdHoc;
     ///
     /// #[launch]
-    /// fn rocket() -> rocket::Rocket {
+    /// fn rocket() -> _ {
     ///     rocket::build()
     ///         .attach(AdHoc::on_liftoff("Print Config", |rocket| Box::pin(async move {
     ///             println!("Rocket launch config: {:?}", rocket.config());
diff --git a/core/lib/src/state.rs b/core/lib/src/state.rs
index c038c4da..57b48fb9 100644
--- a/core/lib/src/state.rs
+++ b/core/lib/src/state.rs
@@ -43,7 +43,7 @@ use crate::http::Status;
 /// }
 ///
 /// #[launch]
-/// fn rocket() -> rocket::Rocket {
+/// fn rocket() -> _ {
 ///     rocket::build()
 ///         .mount("/", routes![index, raw_config_value])
 ///         .manage(MyConfig { user_val: "user input".to_string() })
diff --git a/examples/todo/src/main.rs b/examples/todo/src/main.rs
index 83126386..56908f52 100644
--- a/examples/todo/src/main.rs
+++ b/examples/todo/src/main.rs
@@ -103,7 +103,7 @@ async fn run_migrations(rocket: Rocket) -> Rocket {
 }
 
 #[launch]
-fn rocket() -> Rocket {
+fn rocket() -> _ {
     rocket::build()
         .attach(DbConn::fairing())
         .attach(Template::fairing())
diff --git a/site/guide/10-pastebin.md b/site/guide/10-pastebin.md
index 714792be..a3004943 100644
--- a/site/guide/10-pastebin.md
+++ b/site/guide/10-pastebin.md
@@ -53,7 +53,7 @@ And finally, create a skeleton Rocket application to work off of in
 #[macro_use] extern crate rocket;
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build()
 }
 ```
@@ -110,7 +110,7 @@ to them. To mount the `index` route, modify the main function so that it reads:
 # #[get("/")] fn index() { }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![index])
 }
 ```
@@ -276,7 +276,7 @@ extension trait. Ensure that the route is mounted at the root path:
 # #[post("/")] fn upload() {}
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![index, upload])
 }
 ```
@@ -340,7 +340,7 @@ Make sure that the route is mounted at the root path:
 # #[get("/<id>")] fn retrieve(id: String) {}
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![index, upload, retrieve])
 }
 ```
diff --git a/site/guide/2-getting-started.md b/site/guide/2-getting-started.md
index a5867c3f..c7fa9292 100644
--- a/site/guide/2-getting-started.md
+++ b/site/guide/2-getting-started.md
@@ -71,7 +71,7 @@ fn index() -> &'static str {
 }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![index])
 }
 ```
diff --git a/site/guide/3-overview.md b/site/guide/3-overview.md
index 383ba0c2..8f783582 100644
--- a/site/guide/3-overview.md
+++ b/site/guide/3-overview.md
@@ -155,7 +155,7 @@ fn world() -> &'static str {
 }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/hello", routes![world])
 }
 ```
@@ -181,12 +181,10 @@ Running the application, the console shows:
 
 ! tip: You can also return `_` from a `#[launch]` function!
 
-  If you find it more pleasing, `#[launch]` can infer the return type of
-  `Rocket` for you by using `_` as the return type:
-
-  `
-  #[launch] fn rocket() -> _ { /* ... */ }
-  `
+  Special to Rocket's `#[launch]` attribute, the return type of a function
+  decorated with `#[launch]` is automatically inferred when the return type is
+  set to `_`. If you prefer, you can also set the return type explicitly to
+  `Rocket<Build>`.
 
 If we visit `http://127.0.0.1:8000/hello/world`, we see `Hello, world!`, exactly
 as we expected.
diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md
index 3b5d5f2c..213cffff 100644
--- a/site/guide/4-requests.md
+++ b/site/guide/4-requests.md
@@ -200,7 +200,7 @@ fn user_int(id: isize) { /* ... */ }
 fn user_str(id: &str) { /* ... */ }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![user, user_int, user_str])
 }
 ```
diff --git a/site/guide/6-state.md b/site/guide/6-state.md
index f986d19e..64d2a281 100644
--- a/site/guide/6-state.md
+++ b/site/guide/6-state.md
@@ -291,7 +291,7 @@ use rocket_contrib::databases::diesel;
 struct LogsDbConn(diesel::SqliteConnection);
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().attach(LogsDbConn::fairing())
 }
 ```
diff --git a/site/guide/7-fairings.md b/site/guide/7-fairings.md
index 82528123..777e0aac 100644
--- a/site/guide/7-fairings.md
+++ b/site/guide/7-fairings.md
@@ -51,7 +51,7 @@ example, the following snippet attached two fairings, `req_fairing` and
 ```rust
 # use rocket::launch;
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     # let req_fairing = rocket::fairing::AdHoc::on_request("example", |_, _| Box::pin(async {}));
     # let res_fairing = rocket::fairing::AdHoc::on_response("example", |_, _| Box::pin(async {}));
 
diff --git a/site/guide/8-testing.md b/site/guide/8-testing.md
index 2260c67a..f0ec92ee 100644
--- a/site/guide/8-testing.md
+++ b/site/guide/8-testing.md
@@ -123,7 +123,7 @@ fn hello() -> &'static str {
 }
 
 #[launch]
-fn rocket() -> rocket::Rocket {
+fn rocket() -> _ {
     rocket::build().mount("/", routes![hello])
 }
 ```
@@ -164,7 +164,8 @@ To test our "Hello, world!" application, we create a `Client` for our
 testing: we _want_ our tests to panic when something goes wrong.
 
 ```rust
-# fn rocket() -> rocket::Rocket {
+# #[rocket::launch]
+# fn rocket() -> _ {
 #     rocket::build().reconfigure(rocket::Config::debug_default())
 # }
 # use rocket::local::blocking::Client;
@@ -176,7 +177,8 @@ Then, we create a new `GET /` request and dispatch it, getting back our
 application's response:
 
 ```rust
-# fn rocket() -> rocket::Rocket {
+# #[rocket::launch]
+# fn rocket() -> _ {
 #     rocket::build().reconfigure(rocket::Config::debug_default())
 # }
 # use rocket::local::blocking::Client;