Update module-level docs for 'local', 'local::asynchronous', and 'loc…

…al::blocking'.

core/lib/src/local/asynchronous/mod.rs

@@ -1,3 +1,9 @@
+//! Structures for asynchronous local dispatching of requests, primarily for
+//! testing.
+//!
+//! This module contains the `asynchronous` variant of the `local` API: it can
+//! be used with `#[rocket::async_test]` or another asynchronous test harness.
+
 mod client;
 mod request;
 mod response;

core/lib/src/local/blocking/mod.rs

@@ -1,103 +1,9 @@
-// TODO: Explain difference from async Client
+//! Structures for blocking local dispatching of requests, primarily for
+//! testing.
 //!
-//! Structures for local dispatching of requests, primarily for testing.
-//!
-//! This module allows for simple request dispatching against a local,
-//! non-networked instance of Rocket. The primary use of this module is to unit
-//! and integration test Rocket applications by crafting requests, dispatching
-//! them, and verifying the response.
-//!
-//! # Usage
-//!
-//! This module contains a [`Client`] structure that is used to create
-//! [`LocalRequest`] structures that can be dispatched against a given
-//! [`Rocket`](crate::Rocket) instance. Usage is straightforward:
-//!
-//!   1. Construct a `Rocket` instance that represents the application.
-//!
-//!      ```rust
-//!      let rocket = rocket::ignite();
-//!      # let _ = rocket;
-//!      ```
-//!
-//!   2. Construct a `Client` using the `Rocket` instance.
-//!
-//!      ```rust
-//!      # use rocket::local::blocking::Client;
-//!      # let rocket = rocket::ignite();
-//!      let client = Client::new(rocket).expect("valid rocket instance");
-//!      # let _ = client;
-//!      ```
-//!
-//!   3. Construct requests using the `Client` instance.
-//!
-//!      ```rust
-//!      # use rocket::local::blocking::Client;
-//!      # let rocket = rocket::ignite();
-//!      # let client = Client::new(rocket).unwrap();
-//!      let req = client.get("/");
-//!      # let _ = req;
-//!      ```
-//!
-//!   3. Dispatch the request to retrieve the response.
-//!
-//!      ```rust
-//!      # use rocket::local::blocking::Client;
-//!      # let rocket = rocket::ignite();
-//!      # let client = Client::new(rocket).unwrap();
-//!      # let req = client.get("/");
-//!      let response = req.dispatch();
-//!      # let _ = response;
-//!      ```
-//!
-//! All together and in idiomatic fashion, this might look like:
-//!
-//! ```rust
-//! use rocket::local::blocking::Client;
-//!
-//! let client = Client::new(rocket::ignite()).expect("valid rocket");
-//! let response = client.post("/")
-//!     .body("Hello, world!")
-//!     .dispatch();
-//! # let _ = response;
-//! ```
-//!
-//! # Unit/Integration Testing
-//!
-//! This module can be used to test a Rocket application by constructing
-//! requests via `Client` and validating the resulting response. As an example,
-//! consider the following complete "Hello, world!" application, with testing.
-//!
-//! ```rust
-//! #![feature(proc_macro_hygiene)]
-//!
-//! #[macro_use] extern crate rocket;
-//!
-//! #[get("/")]
-//! fn hello() -> &'static str {
-//!     "Hello, world!"
-//! }
-//!
-//! # fn main() {  }
-//! #[cfg(test)]
-//! mod test {
-//!     use super::{rocket, hello};
-//!     use rocket::local::blocking::Client;
-//!
-//!     fn test_hello_world() {
-//!         // Construct a client to use for dispatching requests.
-//!         let rocket = rocket::ignite().mount("/", routes![hello]);
-//!         let client = Client::new(rocket).expect("valid rocket instance");
-//!
-//!         // Dispatch a request to 'GET /' and validate the response.
-//!         let mut response = client.get("/").dispatch();
-//!         assert_eq!(response.into_string(), Some("Hello, world!".into()));
-//!     }
-//! }
-//! ```
-//!
-//! [`Client`]: crate::local::blocking::Client
-//! [`LocalRequest`]: crate::local::blocking::LocalRequest
+//! This module contains the `blocking` variant of the `local` API: it can be
+//! used in Rust's synchronous `#[test]` harness. This is accomplished by
+//! starting and running an interal asynchronous Runtime as needed.
 
 mod client;
 mod request;

core/lib/src/local/mod.rs

@@ -7,7 +7,14 @@
 //!
 //! # Usage
 //!
-//! This module contains a [`Client`] structure that is used to create
+//! This module contains two variants of the local API: [`asynchronous`] and
+//! [`blocking`]. The primary difference between the two is in usage: the
+//! `asynchronous` API requires an asynchronous test entry point such as
+//! `#[rocket::async_test]`, while the `blocking` API can be used with
+//! `#[test]`. Additionally, several methods in the `asynchronous` API are
+//! `async` and must therefore be `await`ed.
+//!
+//! Both APIs include a [`Client`] structure that is used to create
 //! [`LocalRequest`] structures that can be dispatched against a given
 //! [`Rocket`](crate::Rocket) instance. Usage is straightforward:
 //!