Reviewed docs and made some corrections

Author: Andrew J Westlake

src/async_std.rs

@@ -149,7 +149,7 @@ pub mod testing {
     //! pyo3-asyncio = { version = "0.13", features = ["testing", "async-std-runtime"] }
     //! ```
     //!
-    //! Now, in your test's main file, call [`async_std::testing::test_main`]:
+    //! Now, in your test's main file, call [`crate::async_std::testing::test_main`]:
     //!
     //! ```no_run
     //! fn main() {
@@ -200,11 +200,10 @@ pub mod testing {
         Test::new_async(name, async move { task::spawn_blocking(func).await })
     }
 
-    /// Default main function for the test harness.
+    /// Default main function for the async-std test harness.
     ///
     /// This is meant to perform the necessary initialization for most test cases. If you want
-    /// additional control over the initialization (i.e. env_logger initialization), you can use this
-    /// function as a template.
+    /// additional control over the initialization, you can use this function as a template.
     pub fn test_main(suite_name: &str, tests: Vec<Test>) {
         generic::testing::test_main::<AsyncStdRuntime>(suite_name, tests)
     }

src/generic.rs

@@ -13,21 +13,19 @@ pub trait JoinError {
 
 /// Generic Rust async/await runtime
 pub trait Runtime {
-    /// The type of errors that a JoinHandle can return after awaited
+    /// The error returned by a JoinHandle after being awaited
     type JoinError: JoinError + Send;
     /// A future that completes with the result of the spawned task
     type JoinHandle: Future<Output = Result<(), Self::JoinError>> + Send;
 
-    /// Spawn a function onto this runtime's event loop
+    /// Spawn a future onto this runtime's event loop
     fn spawn<F>(fut: F) -> Self::JoinHandle
     where
         F: Future<Output = ()> + Send + 'static;
 }
 
 /// Run the event loop until the given Future completes
 ///
-/// The event loop runs until the given future is complete.
-///
 /// After this function returns, the event loop can be resumed with either [`run_until_complete`] or
 /// [`crate::run_forever`]
 ///
@@ -264,7 +262,7 @@ where
     Ok(future_rx)
 }
 
-/// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>testing</code></span> Testing Utilities for the Tokio runtime.
+/// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>testing</code></span> Testing utilities for generic runtimes.
 #[cfg(feature = "testing")]
 pub mod testing {
     use pyo3::prelude::*;
@@ -276,10 +274,10 @@ pub mod testing {
         with_runtime,
     };
 
-    /// Default main function for the test harness.
+    /// Default main function for the generic test harness.
     ///
     /// This is meant to perform the necessary initialization for most test cases. If you want
-    /// additional control over the initialization (i.e. env_logger initialization), you can use this
+    /// additional control over the initialization, you can use this
     /// function as a template.
     pub fn test_main<R>(suite_name: &str, tests: Vec<Test>)
     where

src/lib.rs

@@ -15,7 +15,7 @@
 //! Python's coroutines cannot be directly spawned on a Rust event loop. The two coroutine models
 //! require some additional assistance from their event loops, so in all likelihood they will need
 //! a new _unique_ event loop that addresses the needs of both languages if the coroutines are to
-//! be run on the same event loop.
+//! be run on the same loop.
 //!
 //! It's not immediately clear that this would provide worthwhile performance wins either, so in the
 //! interest of keeping things simple, this crate creates and manages the Python event loop and
@@ -218,8 +218,8 @@ pub fn get_event_loop(py: Python) -> &PyAny {
 /// # Python::with_gil(|py| {
 /// # pyo3_asyncio::with_runtime(py, || {
 /// // Wait 1 second, then stop the event loop
-/// tokio::spawn(async move {
-///     tokio::time::sleep(Duration::from_secs(1)).await;
+/// async_std::task::spawn(async move {
+///     async_std::task::sleep(Duration::from_secs(1)).await;
 ///     Python::with_gil(|py| {
 ///         let event_loop = pyo3_asyncio::get_event_loop(py);
 ///         

src/testing.rs

@@ -3,6 +3,10 @@
 //! This module provides some utilities for parsing test arguments as well as running and filtering
 //! a sequence of tests.
 //!
+//! > These utilities are completely independent of the runtime being used. To
+//! > get a more complete picture of how to run tests for PyO3 Asyncio applications, see
+//! > [`crate::async_std::testing`] or [`crate::tokio::testing`] for more details.
+//!
 //! As mentioned [here](crate#pythons-event-loop), PyO3 Asyncio tests cannot use the default test
 //! harness since it doesn't allow Python to gain control over the main thread. Instead, we have to
 //! provide our own test harness in order to create integration tests.

src/tokio.rs

@@ -100,7 +100,7 @@ pub fn init_multi_thread() {
 /// #
 /// # Python::with_gil(|py| {
 /// # pyo3_asyncio::with_runtime(py, || {
-/// pyo3_asyncio::tokio::init_current_thread();
+/// # pyo3_asyncio::tokio::init_current_thread();
 /// pyo3_asyncio::tokio::run_until_complete(py, async move {
 ///     tokio::time::sleep(Duration::from_secs(1)).await;
 ///     Ok(())
@@ -199,10 +199,13 @@ where
 /// pyo3-asyncio = { version = "0.13", features = ["testing", "tokio-runtime"] }
 /// ```
 ///
-/// Now, in your test's main file, call [`crate::tokio::testing::test_main`]:
+/// Now, in your test's main file, initialize the tokio runtime and call
+/// [`crate::tokio::testing::test_main`]:
 ///
 /// ```no_run
 /// fn main() {
+///     pyo3_asyncio::tokio::init_current_thread();
+///
 ///     pyo3_asyncio::tokio::testing::test_main("Example Test Suite", vec![]);
 /// }
 /// ```
@@ -215,6 +218,8 @@ where
 /// use pyo3_asyncio::testing::Test;
 ///
 /// fn main() {
+///     pyo3_asyncio::tokio::init_current_thread();
+///
 ///     pyo3_asyncio::tokio::testing::test_main(
 ///         "Example Test Suite",
 ///         vec![
@@ -259,7 +264,7 @@ pub mod testing {
     /// additional control over the initialization (i.e. env_logger initialization), you can use this
     /// function as a template.
     ///
-    /// Note: The tokio runtime must be initialized before calling this function!
+    /// > _The tokio runtime must be initialized before calling this function!_
     pub fn test_main(suite_name: &str, tests: Vec<Test>) {
         Python::with_gil(|py| {
             with_runtime(py, || {