Fixed some docs for consistency / readability

Author: Andrew J Westlake

src/async_std.rs

@@ -1,3 +1,18 @@
+//! <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>async-std-runtime</code></span> PyO3 Asyncio functions specific to the async-std runtime
+//!
+//! Items marked with
+//! <span
+//!   class="module-item stab portability"
+//!   style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"
+//! ><code>unstable-streams</code></span>
+//! are only available when the `unstable-streams` Cargo feature is enabled:
+//!
+//! ```toml
+//! [dependencies.pyo3-asyncio]
+//! version = "0.16"
+//! features = ["unstable-streams"]
+//! ```
+
 use std::{any::Any, cell::RefCell, future::Future, panic::AssertUnwindSafe, pin::Pin};
 
 use async_std::task;
@@ -491,6 +506,10 @@ pub fn into_future(awaitable: &PyAny) -> PyResult<impl Future<Output = PyResult<
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -534,12 +553,6 @@ pub fn into_future(awaitable: &PyAny) -> PyResult<impl Future<Output = PyResult<
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v1<'p>(
     gen: &'p PyAny,
@@ -549,6 +562,10 @@ pub fn into_stream_v1<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -596,12 +613,6 @@ pub fn into_stream_v1<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v1<'p>(
     locals: TaskLocals,
@@ -612,6 +623,10 @@ pub fn into_stream_with_locals_v1<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -659,12 +674,6 @@ pub fn into_stream_with_locals_v1<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v2<'p>(
     locals: TaskLocals,
@@ -675,6 +684,10 @@ pub fn into_stream_with_locals_v2<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -718,10 +731,6 @@ pub fn into_stream_with_locals_v2<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v2<'p>(
     gen: &'p PyAny,

src/generic.rs

@@ -1119,6 +1119,10 @@ where
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -1213,12 +1217,6 @@ where
 /// Ok(())
 /// # }
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v1<'p, R>(
     locals: TaskLocals,
@@ -1266,6 +1264,10 @@ where
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -1356,12 +1358,6 @@ where
 /// Ok(())
 /// # }
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v1<'p, R>(
     gen: &'p PyAny,
@@ -1471,6 +1467,10 @@ async def forward(gen, sender):
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -1565,12 +1565,6 @@ async def forward(gen, sender):
 /// Ok(())
 /// # }
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v2<'p, R>(
     locals: TaskLocals,
@@ -1619,6 +1613,10 @@ where
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -1709,12 +1707,6 @@ where
 /// Ok(())
 /// # }
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v2<'p, R>(
     gen: &'p PyAny,

src/lib.rs

@@ -350,11 +350,9 @@ pub use inventory;
 #[cfg(feature = "testing")]
 pub mod testing;
 
-/// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>async-std-runtime</code></span> PyO3 Asyncio functions specific to the async-std runtime
 #[cfg(feature = "async-std")]
 pub mod async_std;
 
-/// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>tokio-runtime</code></span> PyO3 Asyncio functions specific to the tokio runtime
 #[cfg(feature = "tokio-runtime")]
 pub mod tokio;
 

src/tokio.rs

@@ -1,3 +1,18 @@
+//! <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>tokio-runtime</code></span> PyO3 Asyncio functions specific to the tokio runtime
+//!
+//! Items marked with
+//! <span
+//!   class="module-item stab portability"
+//!   style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"
+//! ><code>unstable-streams</code></span>
+//! are only available when the `unstable-streams` Cargo feature is enabled:
+//!
+//! ```toml
+//! [dependencies.pyo3-asyncio]
+//! version = "0.16"
+//! features = ["unstable-streams"]
+//! ```
+
 use std::{future::Future, pin::Pin, sync::Mutex};
 
 use ::tokio::{
@@ -539,6 +554,10 @@ pub fn into_future(awaitable: &PyAny) -> PyResult<impl Future<Output = PyResult<
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -586,12 +605,6 @@ pub fn into_future(awaitable: &PyAny) -> PyResult<impl Future<Output = PyResult<
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v1<'p>(
     locals: TaskLocals,
@@ -602,6 +615,10 @@ pub fn into_stream_with_locals_v1<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -645,12 +662,6 @@ pub fn into_stream_with_locals_v1<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v1<'p>(
     gen: &'p PyAny,
@@ -660,6 +671,10 @@ pub fn into_stream_v1<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `locals` - The current task locals
 /// * `gen` - The Python async generator to be converted
@@ -707,12 +722,6 @@ pub fn into_stream_v1<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// # Availability
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_with_locals_v2<'p>(
     locals: TaskLocals,
@@ -723,6 +732,10 @@ pub fn into_stream_with_locals_v2<'p>(
 
 /// <span class="module-item stab portability" style="display: inline; border-radius: 3px; padding: 2px; font-size: 80%; line-height: 1.2;"><code>unstable-streams</code></span> Convert an async generator into a stream
 ///
+/// **This API is marked as unstable** and is only available when the
+/// `unstable-streams` crate feature is enabled. This comes with no
+/// stability guarantees, and could be changed or removed at any time.
+///
 /// # Arguments
 /// * `gen` - The Python async generator to be converted
 ///
@@ -766,10 +779,6 @@ pub fn into_stream_with_locals_v2<'p>(
 /// # #[cfg(not(all(feature = "unstable-streams", feature = "attributes")))]
 /// # fn main() {}
 /// ```
-///
-/// **This API is marked as unstable** and is only available when the
-/// `unstable-streams` crate feature is enabled. This comes with no
-/// stability guarantees, and could be changed or removed at any time.
 #[cfg(feature = "unstable-streams")]
 pub fn into_stream_v2<'p>(
     gen: &'p PyAny,