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,91 +21,111 @@ 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 [`Orbit`] phase represents a _running_ application,
+///   An instance in the [`Ignite`] phase is in its final configuration,
-/// actively serving requests.
+///   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:
 ///
-/// To launch an instance of `Rocket`, it _must_ progress through all three
+///   ```rust,no_run
-/// phases. To progress into the ignite or launch phases, a tokio `async`
+///   # use rocket::launch;
-/// runtime is required. The [`#[main]`](crate::main) attribute initializes a
+///   #[launch]
-/// Rocket-specific tokio runtime and runs the attributed `async fn` inside of
+///   fn rocket() -> _ {
-/// it:
+///       rocket::build()
+///   }
+///   ```
 ///
-/// ```rust,no_run
+/// This generates a `main` funcion with an `async` runtime that runs the
-/// #[rocket::main]
+/// returned `Rocket` instance.
-/// async fn main() -> Result<(), rocket::Error> {
-///     rocket::build()
-///         .ignite().await?
-///         .launch().await
-/// }
-/// ```
 ///
-/// Note that [`Rocket::launch()`] automatically progresses an instance of
+/// * **Manual Launching**
-/// `Rocket` from any phase into orbit:
 ///
-/// ```rust,no_run
+///   To launch an instance of `Rocket`, it _must_ progress through all three
-/// #[rocket::main]
+///   phases. To progress into the ignite or launch phases, a tokio `async`
-/// async fn main() -> Result<(), rocket::Error> {
+///   runtime is required. The [`#[main]`](crate::main) attribute initializes a
-///     rocket::build().launch().await
+///   Rocket-specific tokio runtime and runs the attributed `async fn` inside of
-/// }
+///   it:
-/// ```
 ///
-/// ## Automatic Launching
+///   ```rust,no_run
+///   #[rocket::main]
+///   async fn main() -> Result<(), rocket::Error> {
+///       rocket::build()
+///           .ignite().await?
+///           .launch().await
+///   }
+///   ```
 ///
-/// Manually progressing an instance of Rocket though its phases is only
+///   Note that [`Rocket::launch()`] automatically progresses an instance of
-/// necessary when either an instance's finalized state is to be inspected (in
+///   `Rocket` from any phase into orbit:
-/// the _ignite_ phase) or the instance is expected to deorbit due to
-/// [`Rocket::shutdown()`]. In the more common case when neither is required,
-/// the [`#[launch]`](crate::launch) attribute can be used. When applied to a
-/// function that returns a `Rocket<Build>`, it automatically initializes an
-/// `async` runtime and launches the function's returned instance:
 ///
-/// ```rust,no_run
+///   ```rust,no_run
-/// # use rocket::launch;
+///   #[rocket::main]
-/// use rocket::{Rocket, Build};
+///   async fn main() -> Result<(), rocket::Error> {
+///       rocket::build().launch().await
+///   }
+///   ```
 ///
-/// #[launch]
+/// * **Automatic Launching**
-/// fn rocket() -> Rocket<Build> {
-///     rocket::build()
-/// }
-/// ```
 ///
-/// To avoid needing to import _any_ items in the common case, the `launch`
+///   Manually progressing an instance of Rocket though its phases is only
-/// attribute will infer a return type written as `_` as `Rocket<Build>`:
+///   necessary when either an instance's finalized state is to be inspected (in
+///   the _ignite_ phase) or the instance is expected to deorbit due to
+///   [`Rocket::shutdown()`]. In the more common case when neither is required,
+///   the [`#[launch]`](crate::launch) attribute can be used. When applied to a
+///   function that returns a `Rocket<Build>`, it automatically initializes an
+///   `async` runtime and launches the function's returned instance:
 ///
-/// ```rust,no_run
+///   ```rust,no_run
-/// # use rocket::launch;
+///   # use rocket::launch;
-/// #[launch]
+///   use rocket::{Rocket, Build};
-/// fn rocket() -> _ {
+///
-///     rocket::build()
+///   #[launch]
-/// }
+///   fn rocket() -> Rocket<Build> {
-/// ```
+///       rocket::build()
+///   }
+///   ```
+///
+///   To avoid needing to import _any_ items in the common case, the `launch`
+///   attribute will infer a return type written as `_` as `Rocket<Build>`:
+///
+///   ```rust,no_run
+///   # use rocket::launch;
+///   #[launch]
+///   fn rocket() -> _ {
+///       rocket::build()
+///   }
+///   ```
 #[must_use]
 pub struct Rocket<P: Phase>(pub(crate) P::State);