Merge pull request #459 from stjepang/expose-ext-traits

Expose extension traits in preludes

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<Self::Output>;
     }
 
+    #[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.
         ///

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.

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)]
+#[doc(inline)]
-pub use crate::io::buf_read::BufReadExt as _;
+pub use crate::io::buf_read::BufReadExt;
-#[doc(hidden)]
+#[doc(inline)]
-pub use crate::io::read::ReadExt as _;
+pub use crate::io::read::ReadExt;
-#[doc(hidden)]
+#[doc(inline)]
-pub use crate::io::seek::SeekExt as _;
+pub use crate::io::seek::SeekExt;
-#[doc(hidden)]
+#[doc(inline)]
-pub use crate::io::write::WriteExt as _;
+pub use crate::io::write::WriteExt;

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.

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<io::Result<u64>>;
     }
 
+    #[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.

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();
     ///

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<io::Result<()>>;
     }
 
+    #[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.

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;
+pub use crate::io::prelude::BufReadExt as _;
 #[doc(no_inline)]
-pub use crate::task_local;
+pub use crate::io::prelude::ReadExt as _;
-
+#[doc(no_inline)]
-#[doc(hidden)]
+pub use crate::io::prelude::SeekExt as _;
-pub use crate::future::future::FutureExt as _;
+#[doc(no_inline)]
-#[doc(hidden)]
+pub use crate::io::prelude::WriteExt as _;
-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 _;
 
 cfg_unstable! {
     #[doc(no_inline)]

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<T> {
     ///
     /// ```
     /// # 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);
     ///

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<Option<Self::Item>>;
     }
 
+    #[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.

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
+//! [`Arc`]: struct.Arc.html
-//! [`Barrier`]: crate::sync::Barrier
+//! [`Barrier`]: struct.Barrier.html
-//! [`Condvar`]: crate::sync::Condvar
 //! [`channel`]: fn.channel.html
-//! [`Mutex`]: crate::sync::Mutex
+//! [`Mutex`]: struct.Mutex.html
-//! [`Once`]: crate::sync::Once
+//! [`RwLock`]: struct.RwLock.html
-//! [`RwLock`]: crate::sync::RwLock
 //!
 //! # Examples
 //!

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.
+        #[doc = $doc_ext]
-        pub trait $ext: $base {
+        pub trait $ext: $name {
             extension_trait!(@ext () $($body_ext)*);
         }
 
         // Blanket implementation of the extension trait for any type implementing the base trait.
-        impl<T: $base + ?Sized> $ext for T {}
+        impl<T: $name + ?Sized> $ext for T {}
 
         // Shim trait impls that only appear in docs.
         $(#[cfg(feature = "docs")] $imp)*