Improve and clarify 'Rocket' phase docs.

core/lib/src/phase.rs

@@ -73,11 +73,11 @@ macro_rules! phases {
 }
 
 phases! {
-    /// The initial launch [`Phase`].
+    /// The initial launch [`Phase`]. See [Rocket#build](`Rocket#build`) for
+    /// phase details.
     ///
-    /// An instance of `Rocket` in this phase is typed as [`Rocket<Build>`] and
+    /// An instance of `Rocket` in this phase is typed as [`Rocket<Build>`]: a
-    /// represents a transient, in-progress build. See [`Rocket#build`] for
+    /// transient, in-progress build.
-    /// details.
     Build (#[derive(Default, Debug)] Building) {
         pub(crate) routes: Vec<Route>,
         pub(crate) catchers: Vec<Catcher>,
@@ -86,7 +86,8 @@ phases! {
         pub(crate) state: Container![Send + Sync],
     }
 
-    /// The second launch [`Phase`]: post-build but pre-orbit.
+    /// The second launch [`Phase`]: post-build but pre-orbit. See
+    /// [Rocket#ignite](`Rocket#ignite`) for details.
     ///
     /// An instance of `Rocket` in this phase is typed as [`Rocket<Ignite>`] and
     /// represents a fully built and finalized application server ready for
@@ -100,10 +101,11 @@ phases! {
         pub(crate) shutdown: Shutdown,
     }
 
-    /// The final launch [`Phase`].
+    /// The final launch [`Phase`]. See [Rocket#orbit](`Rocket#orbit`) for
+    /// details.
     ///
     /// An instance of `Rocket` in this phase is typed as [`Rocket<Orbit>`] and
-    /// represents a running application. See [`Rocket#orbit`] for full details.
+    /// represents a running application.
     Orbit (#[derive(Debug)] Orbiting) {
         pub(crate) router: Router,
         pub(crate) fairings: Fairings,

core/lib/src/rocket.rs

@@ -21,35 +21,55 @@ use crate::log::PaintExt;
 ///
 /// # Phases
 ///
-/// An instance of `Rocket` represents a web server and its state. It progresses
+/// A `Rocket` instance represents a web server and its state. It progresses
-/// through three statically-enforced phases into orbit: build, ignite, orbit.
+/// through three statically-enforced phases: build, ignite, orbit.
 ///
-/// ## Build
+/// * **Build**: _application and server configuration_
 ///
-/// All application and server configuration occurs during the [`Build`] phase.
+///   This phase enables:
-/// This includes setting configuration options, mounting/registering
-/// routes/catchers, managing state, and attaching fairings. This is the _only_
-/// phase in which an instance can be modified. To finalize changes, an instance
-/// is ignited via [`Rocket::ignite()`], progressing it into the _ignite_ phase,
-/// or directly launched into orbit with [`Rocket::launch()`] which progress the
-/// instance through ignite into orbit.
 ///
-/// ## Ignite
+///     * setting configuration options
+///     * mounting/registering routes/catchers
+///     * managing state
+///     * attaching fairings
 ///
-/// An instance in the [`Ignite`] phase is in its final configuration, available
+///   This is the _only_ phase in which an instance can be modified. To finalize
-/// via [`Rocket::config()`]. Barring user-supplied iterior mutation,
+///   changes, an instance is ignited via [`Rocket::ignite()`], progressing it
-/// application state is guaranteed to remain unchanged beyond this point. An
+///   into the _ignite_ phase, or directly launched into orbit with
-/// instance in the ignite phase can be launched into orbit to serve requests
+///   [`Rocket::launch()`] which progress the instance through ignite into
-/// via [`Rocket::launch()`].
+///   orbit.
 ///
-/// ## Orbit
+/// * **Ignite**: _verification and finalization of configuration_
+///
+///   An instance in the [`Ignite`] phase is in its final configuration,
+///   available via [`Rocket::config()`]. Barring user-supplied iterior
+///   mutation, application state is guaranteed to remain unchanged beyond this
+///   point. An instance in the ignite phase can be launched into orbit to serve
+///   requests via [`Rocket::launch()`].
+///
+/// * **Orbit**: _a running web server_
 ///
 ///   An instance in the [`Orbit`] phase represents a _running_ application,
 ///   actively serving requests.
 ///
 /// # Launching
 ///
-/// ## Manual Launching
+/// To launch a `Rocket` application, the suggested approach is to return an
+/// instance of `Rocket<Build>` from a function named `rocket` marked with the
+/// [`#[launch]`](crate::launch) attribute:
+///
+///   ```rust,no_run
+///   # use rocket::launch;
+///   #[launch]
+///   fn rocket() -> _ {
+///       rocket::build()
+///   }
+///   ```
+///
+/// This generates a `main` funcion with an `async` runtime that runs the
+/// returned `Rocket` instance.
+///
+/// * **Manual Launching**
 ///
 ///   To launch an instance of `Rocket`, it _must_ progress through all three
 ///   phases. To progress into the ignite or launch phases, a tokio `async`
@@ -76,7 +96,7 @@ use crate::log::PaintExt;
 ///   }
 ///   ```
 ///
-/// ## Automatic Launching
+/// * **Automatic Launching**
 ///
 ///   Manually progressing an instance of Rocket though its phases is only
 ///   necessary when either an instance's finalized state is to be inspected (in