Docs cleanup

src/asynch.rs

@@ -1,4 +1,9 @@
-//! Shuttle's implementation of `async_runtime::spawn`.
+//! Shuttle's implementation of an async executor, roughly equivalent to [`futures::executor`].
+//!
+//! The [spawn] method spawns a new asynchronous task that the executor will run to completion. The
+//! [block_on] method blocks the current thread on the completion of a future.
+//!
+//! [`futures::executor`]: https://docs.rs/futures/0.3.13/futures/executor/index.html
 
 use crate::runtime::execution::ExecutionState;
 use crate::runtime::task::{TaskId, TaskType};
@@ -8,7 +13,7 @@ use std::pin::Pin;
 use std::result::Result;
 use std::task::{Context, Poll};
 
-/// Spawn a new async task.
+/// Spawn a new async task that the executor will run to completion.
 pub fn spawn<T, F>(fut: F) -> JoinHandle<T>
 where
     F: Future<Output = T> + Send + 'static,
@@ -110,7 +115,7 @@ where
     }
 }
 
-/// Block a thread on a future
+/// Run a future to completion on the current thread.
 pub fn block_on<T, F>(future: F) -> T
 where
     F: Future<Output = T> + Send + 'static,

src/lib.rs

@@ -125,9 +125,9 @@
 //! ## Writing Shuttle tests
 //!
 //! To test concurrent code with Shuttle, all uses of synchronization primitives from `std` must be
-//! replaced by their Shuttle equivalents. We've found that the simplest way to do this is via `cfg`
-//! flags. Specifically, if you enforce that all synchronization primitives are imported from a
-//! single `sync` module in your code, and implement that module like this:
+//! replaced by their Shuttle equivalents. The simplest way to do this is via `cfg` flags.
+//! Specifically, if you enforce that all synchronization primitives are imported from a single
+//! `sync` module in your code, and implement that module like this:
 //!
 //! ```
 //! #[cfg(all(feature = "shuttle", test))]
@@ -176,8 +176,8 @@
 //! with the [`Runner::run`] method. Shuttle also provides a [`PortfolioRunner`] object for running
 //! multiple schedulers, using parallelism to increase the number of test executions explored.
 //!
-//! [Loom]: https://github.com/tokio-rs/loom
-//! [pct]: https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/asplos277-pct.pdf
+//! [Loom]: https://github.com/tokio-rs/loom [pct]:
+//! https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/asplos277-pct.pdf
 
 pub mod asynch;
 pub mod rand;

src/rand.rs

@@ -1,5 +1,9 @@
-//! Shuttle's implementation of the `rand` crate. Shuttle captures and controls the nondeterminism
-//! introduced by randomness and allows it to be replayed deterministically.
+//! Shuttle's implementation of the [`rand`] crate, v0.7.
+//!
+//! Shuttle captures and controls the nondeterminism introduced by randomness and allows it to be
+//! replayed deterministically.
+//!
+//! [`rand`]: https://docs.rs/rand/0.7.3/rand/index.html
 
 /// Random number generators and adapters
 pub mod rngs {

src/sync/mod.rs

@@ -1,4 +1,4 @@
-//! Shuttle's implementation of `std::sync`.
+//! Shuttle's implementation of [`std::sync`].
 
 mod barrier;
 mod condvar;

src/thread.rs

@@ -1,4 +1,4 @@
-//! Shuttle's implementation of `std::thread`.
+//! Shuttle's implementation of [`std::thread`].
 
 use crate::runtime::execution::ExecutionState;
 use crate::runtime::task::{TaskId, TaskType};