From a757cc02dc721b1128a8bcaa49cc68822a08525f Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Wed, 6 Nov 2019 00:21:32 +0100 Subject: [PATCH 1/2] Expose extension traits in preludes --- src/future/future/mod.rs | 16 ++++++++++++++++ src/io/buf_read/mod.rs | 9 ++++++++- src/io/prelude.rs | 18 +++++++++--------- src/io/read/mod.rs | 9 ++++++++- src/io/seek/mod.rs | 9 ++++++++- src/io/stdin.rs | 2 +- src/io/write/mod.rs | 9 ++++++++- src/prelude.rs | 32 +++++++++++++++++--------------- src/stream/from_stream.rs | 6 ++---- src/stream/stream/mod.rs | 9 ++++++++- src/sync/mod.rs | 12 +++++------- src/utils.rs | 7 ++++--- 12 files changed, 94 insertions(+), 44 deletions(-) diff --git a/src/future/future/mod.rs b/src/future/future/mod.rs index 2cd5c7e..548cccb 100644 --- a/src/future/future/mod.rs +++ b/src/future/future/mod.rs @@ -23,6 +23,14 @@ extension_trait! { "asynchronous value" makes it possible for a thread to continue doing useful work while it waits for the value to become available. + The [provided methods] do not really exist in the trait itself, but they become + available when [`FutureExt`] from the [prelude] is imported: + + ``` + # #[allow(unused_imports)] + use async_std::prelude::*; + ``` + # The `poll` method The core method of future, `poll`, *attempts* to resolve the future into a @@ -36,6 +44,9 @@ extension_trait! { `.await` the value. [`Waker`]: ../task/struct.Waker.html + [provided methods]: #provided-methods + [`FutureExt`]: ../prelude/trait.FutureExt.html + [prelude]: ../prelude/index.html "#] pub trait Future { #[doc = r#" @@ -110,6 +121,11 @@ extension_trait! { fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll; } + #[doc = r#" + Extension methods for [`Future`]. + + [`Future`]: ../future/trait.Future.html + "#] pub trait FutureExt: std::future::Future { /// Returns a Future that delays execution for a specified time. /// diff --git a/src/io/buf_read/mod.rs b/src/io/buf_read/mod.rs index b82971f..45c5f28 100644 --- a/src/io/buf_read/mod.rs +++ b/src/io/buf_read/mod.rs @@ -25,7 +25,7 @@ extension_trait! { [`std::io::BufRead`]. The [provided methods] do not really exist in the trait itself, but they become - available when the prelude is imported: + available when [`BufReadExt`] from the [prelude] is imported: ``` # #[allow(unused_imports)] @@ -36,6 +36,8 @@ extension_trait! { [`futures::io::AsyncBufRead`]: https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncBufRead.html [provided methods]: #provided-methods + [`BufReadExt`]: ../io/prelude/trait.BufReadExt.html + [prelude]: ../prelude/index.html "#] pub trait BufRead { #[doc = r#" @@ -62,6 +64,11 @@ extension_trait! { fn consume(self: Pin<&mut Self>, amt: usize); } + #[doc = r#" + Extension methods for [`BufRead`]. + + [`BufRead`]: ../trait.BufRead.html + "#] pub trait BufReadExt: futures_io::AsyncBufRead { #[doc = r#" Reads all bytes into `buf` until the delimiter `byte` or EOF is reached. diff --git a/src/io/prelude.rs b/src/io/prelude.rs index fb1b945..c90b289 100644 --- a/src/io/prelude.rs +++ b/src/io/prelude.rs @@ -1,4 +1,4 @@ -//! The async I/O Prelude +//! The async I/O prelude. //! //! The purpose of this module is to alleviate imports of many common I/O traits //! by adding a glob import to the top of I/O heavy modules: @@ -17,11 +17,11 @@ pub use crate::io::Seek; #[doc(no_inline)] pub use crate::io::Write; -#[doc(hidden)] -pub use crate::io::buf_read::BufReadExt as _; -#[doc(hidden)] -pub use crate::io::read::ReadExt as _; -#[doc(hidden)] -pub use crate::io::seek::SeekExt as _; -#[doc(hidden)] -pub use crate::io::write::WriteExt as _; +#[doc(inline)] +pub use crate::io::buf_read::BufReadExt; +#[doc(inline)] +pub use crate::io::read::ReadExt; +#[doc(inline)] +pub use crate::io::seek::SeekExt; +#[doc(inline)] +pub use crate::io::write::WriteExt; diff --git a/src/io/read/mod.rs b/src/io/read/mod.rs index f5c0a4c..56f6323 100644 --- a/src/io/read/mod.rs +++ b/src/io/read/mod.rs @@ -31,7 +31,7 @@ extension_trait! { [`std::io::Read`]. Methods other than [`poll_read`] and [`poll_read_vectored`] do not really exist in the - trait itself, but they become available when the prelude is imported: + trait itself, but they become available when [`ReadExt`] from the [prelude] is imported: ``` # #[allow(unused_imports)] @@ -43,6 +43,8 @@ extension_trait! { https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncRead.html [`poll_read`]: #tymethod.poll_read [`poll_read_vectored`]: #method.poll_read_vectored + [`ReadExt`]: ../io/prelude/trait.ReadExt.html + [prelude]: ../prelude/index.html "#] pub trait Read { #[doc = r#" @@ -66,6 +68,11 @@ extension_trait! { } } + #[doc = r#" + Extension methods for [`Read`]. + + [`Read`]: ../trait.Read.html + "#] pub trait ReadExt: futures_io::AsyncRead { #[doc = r#" Reads some bytes from the byte stream. diff --git a/src/io/seek/mod.rs b/src/io/seek/mod.rs index ec2dd8f..7dc30ae 100644 --- a/src/io/seek/mod.rs +++ b/src/io/seek/mod.rs @@ -18,7 +18,7 @@ extension_trait! { [`std::io::Seek`]. The [provided methods] do not really exist in the trait itself, but they become - available when the prelude is imported: + available when [`SeekExt`] the [prelude] is imported: ``` # #[allow(unused_imports)] @@ -29,6 +29,8 @@ extension_trait! { [`futures::io::AsyncSeek`]: https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncSeek.html [provided methods]: #provided-methods + [`SeekExt`]: ../io/prelude/trait.SeekExt.html + [prelude]: ../prelude/index.html "#] pub trait Seek { #[doc = r#" @@ -41,6 +43,11 @@ extension_trait! { ) -> Poll>; } + #[doc = r#" + Extension methods for [`Seek`]. + + [`Seek`]: ../trait.Seek.html + "#] pub trait SeekExt: futures_io::AsyncSeek { #[doc = r#" Seeks to a new position in a byte stream. diff --git a/src/io/stdin.rs b/src/io/stdin.rs index 26b7ee0..bd6580c 100644 --- a/src/io/stdin.rs +++ b/src/io/stdin.rs @@ -173,7 +173,7 @@ impl Stdin { /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async { /// # /// use async_std::io; - /// use crate::async_std::prelude::*; + /// use async_std::prelude::*; /// /// let mut buffer = String::new(); /// diff --git a/src/io/write/mod.rs b/src/io/write/mod.rs index a07c896..eb11434 100644 --- a/src/io/write/mod.rs +++ b/src/io/write/mod.rs @@ -26,7 +26,7 @@ extension_trait! { Methods other than [`poll_write`], [`poll_write_vectored`], [`poll_flush`], and [`poll_close`] do not really exist in the trait itself, but they become available when - the prelude is imported: + [`WriteExt`] from the [prelude] is imported: ``` # #[allow(unused_imports)] @@ -40,6 +40,8 @@ extension_trait! { [`poll_write_vectored`]: #method.poll_write_vectored [`poll_flush`]: #tymethod.poll_flush [`poll_close`]: #tymethod.poll_close + [`WriteExt`]: ../io/prelude/trait.WriteExt.html + [prelude]: ../prelude/index.html "#] pub trait Write { #[doc = r#" @@ -74,6 +76,11 @@ extension_trait! { fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll>; } + #[doc = r#" + Extension methods for [`Write`]. + + [`Write`]: ../trait.Write.html + "#] pub trait WriteExt: futures_io::AsyncWrite { #[doc = r#" Writes some bytes into the byte stream. diff --git a/src/prelude.rs b/src/prelude.rs index 91432e0..93218f1 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -13,6 +13,16 @@ #[doc(no_inline)] pub use crate::future::Future; +#[doc(no_inline)] +pub use crate::stream::Stream; +#[doc(no_inline)] +pub use crate::task_local; + +#[doc(inline)] +pub use crate::future::future::FutureExt; +#[doc(inline)] +pub use crate::stream::stream::StreamExt; + #[doc(no_inline)] pub use crate::io::BufRead as _; #[doc(no_inline)] @@ -21,23 +31,15 @@ pub use crate::io::Read as _; pub use crate::io::Seek as _; #[doc(no_inline)] pub use crate::io::Write as _; -#[doc(no_inline)] -pub use crate::stream::Stream; -#[doc(no_inline)] -pub use crate::task_local; -#[doc(hidden)] -pub use crate::future::future::FutureExt as _; -#[doc(hidden)] +#[doc(no_inline)] pub use crate::io::buf_read::BufReadExt as _; -#[doc(hidden)] -pub use crate::io::read::ReadExt as _; -#[doc(hidden)] -pub use crate::io::seek::SeekExt as _; -#[doc(hidden)] -pub use crate::io::write::WriteExt as _; -#[doc(hidden)] -pub use crate::stream::stream::StreamExt as _; +#[doc(no_inline)] +pub use crate::io::prelude::ReadExt as _; +#[doc(no_inline)] +pub use crate::io::prelude::SeekExt as _; +#[doc(no_inline)] +pub use crate::io::prelude::WriteExt as _; cfg_unstable! { #[doc(no_inline)] diff --git a/src/stream/from_stream.rs b/src/stream/from_stream.rs index 54a2229..e8707ce 100644 --- a/src/stream/from_stream.rs +++ b/src/stream/from_stream.rs @@ -15,9 +15,8 @@ use std::pin::Pin; /// /// ``` /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async { -/// use crate::async_std::stream::FromStream; /// use async_std::prelude::*; -/// use async_std::stream; +/// use async_std::stream::{self, FromStream}; /// /// let five_fives = stream::repeat(5).take(5); /// @@ -117,9 +116,8 @@ pub trait FromStream { /// /// ``` /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async { - /// use crate::async_std::stream::FromStream; /// use async_std::prelude::*; - /// use async_std::stream; + /// use async_std::stream::{self, FromStream}; /// /// let five_fives = stream::repeat(5).take(5); /// diff --git a/src/stream/stream/mod.rs b/src/stream/stream/mod.rs index b77019d..990ef7b 100644 --- a/src/stream/stream/mod.rs +++ b/src/stream/stream/mod.rs @@ -138,7 +138,7 @@ extension_trait! { [`std::iter::Iterator`]. The [provided methods] do not really exist in the trait itself, but they become - available when the prelude is imported: + available when [`StreamExt`] from the [prelude] is imported: ``` # #[allow(unused_imports)] @@ -149,6 +149,8 @@ extension_trait! { [`futures::stream::Stream`]: https://docs.rs/futures-preview/0.3.0-alpha.17/futures/stream/trait.Stream.html [provided methods]: #provided-methods + [`StreamExt`]: ../prelude/trait.StreamExt.html + [prelude]: ../prelude/index.html "#] pub trait Stream { #[doc = r#" @@ -210,6 +212,11 @@ extension_trait! { fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll>; } + #[doc = r#" + Extension methods for [`Stream`]. + + [`Stream`]: ../stream/trait.Stream.html + "#] pub trait StreamExt: futures_core::stream::Stream { #[doc = r#" Advances the stream and returns the next value. diff --git a/src/sync/mod.rs b/src/sync/mod.rs index ea991fe..ab551ec 100644 --- a/src/sync/mod.rs +++ b/src/sync/mod.rs @@ -134,7 +134,7 @@ //! inter-task synchronisation mechanism, at the cost of some //! extra memory. //! -//! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at +//! - [`Mutex`]: Mutual exclusion mechanism, which ensures that at //! most one task at a time is able to access some data. //! //! - [`RwLock`]: Provides a mutual exclusion mechanism which allows @@ -142,13 +142,11 @@ //! writer at a time. In some cases, this can be more efficient than //! a mutex. //! -//! [`Arc`]: crate::sync::Arc -//! [`Barrier`]: crate::sync::Barrier -//! [`Condvar`]: crate::sync::Condvar +//! [`Arc`]: struct.Arc.html +//! [`Barrier`]: struct.Barrier.html //! [`channel`]: fn.channel.html -//! [`Mutex`]: crate::sync::Mutex -//! [`Once`]: crate::sync::Once -//! [`RwLock`]: crate::sync::RwLock +//! [`Mutex`]: struct.Mutex.html +//! [`RwLock`]: struct.RwLock.html //! //! # Examples //! diff --git a/src/utils.rs b/src/utils.rs index a1d8510..7758cc7 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -144,6 +144,7 @@ macro_rules! extension_trait { $($body_base:tt)* } + #[doc = $doc_ext:tt] pub trait $ext:ident: $base:path { $($body_ext:tt)* } @@ -177,13 +178,13 @@ macro_rules! extension_trait { pub use $base as $name; // The extension trait that adds methods to any type implementing the base trait. - /// Extension trait. - pub trait $ext: $base { + #[doc = $doc_ext] + pub trait $ext: $name { extension_trait!(@ext () $($body_ext)*); } // Blanket implementation of the extension trait for any type implementing the base trait. - impl $ext for T {} + impl $ext for T {} // Shim trait impls that only appear in docs. $(#[cfg(feature = "docs")] $imp)* From c3254d78d9d89df0386d86f6a3ddf8626d6944c3 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Wed, 6 Nov 2019 01:17:35 +0100 Subject: [PATCH 2/2] Fix a re-rexport --- src/prelude.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/prelude.rs b/src/prelude.rs index 93218f1..f8583fd 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -33,7 +33,7 @@ pub use crate::io::Seek as _; pub use crate::io::Write as _; #[doc(no_inline)] -pub use crate::io::buf_read::BufReadExt as _; +pub use crate::io::prelude::BufReadExt as _; #[doc(no_inline)] pub use crate::io::prelude::ReadExt as _; #[doc(no_inline)]