Merge async-rs#241

241: Simplify extension traits using a macro r=yoshuawuyts a=stjepang This PR would fix async-rs#235 Async methods in our extension traits are now written in the simpler `-> impl Future<Output = T> [ConcreteFuture<Self>]` style. At the same time, doc tests are used even when the `docs` feature is not enabled. Co-authored-by: Stjepan Glavina <stjepang@gmail.com>

Author: bors[bot]

src/io/buf_read/mod.rs

@@ -5,119 +5,114 @@ use cfg_if::cfg_if;
 use crate::future::Future;
 use crate::io::{self, SeekFrom};
 use crate::task::{Context, Poll};
+use crate::utils::extension_trait;
 
 cfg_if! {
  if #[cfg(feature = "docs")] {
  use std::ops::{Deref, DerefMut};
+ }
+}
 
- #[doc(hidden)]
- pub struct ImplFuture<T>(std::marker::PhantomData<T>);
-
- /// Allows seeking through a byte stream.
- ///
- /// This trait is a re-export of [`futures::io::AsyncSeek`] and is an async version of
- /// [`std::io::Seek`].
- ///
- /// The [provided methods] do not really exist in the trait itself, but they become
- /// available when the prelude is imported:
- ///
- /// ```
- /// # #[allow(unused_imports)]
- /// use async_std::prelude::*;
- /// ```
- ///
- /// [`std::io::Seek`]: https://doc.rust-lang.org/std/io/trait.Seek.html
- /// [`futures::io::AsyncSeek`]:
- /// https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncSeek.html
- /// [provided methods]: #provided-methods
- pub trait Seek {
- /// Attempt to seek to an offset, in bytes, in a stream.
- fn poll_seek(
- self: Pin<&mut Self>,
- cx: &mut Context<'_>,
- pos: SeekFrom,
- ) -> Poll<io::Result<u64>>;
-
- /// Seeks to a new position in a byte stream.
- ///
- /// Returns the new position in the byte stream.
- ///
- /// A seek beyond the end of stream is allowed, but behavior is defined by the
- /// implementation.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
- /// #
- /// use async_std::fs::File;
- /// use async_std::io::SeekFrom;
- /// use async_std::prelude::*;
- ///
- /// let mut file = File::open("a.txt").await?;
- ///
- /// let file_len = file.seek(SeekFrom::End(0)).await?;
- /// #
- /// # Ok(()) }) }
- /// ```
- fn seek(&mut self, pos: SeekFrom) -> ImplFuture<io::Result<u64>>
- where
- Self: Unpin
- {
- unreachable!()
- }
- }
+extension_trait! {
+ #[doc = r#"
+ Allows seeking through a byte stream.
 
- impl<T: Seek + Unpin + ?Sized> Seek for Box<T> {
- fn poll_seek(
- self: Pin<&mut Self>,
- cx: &mut Context<'_>,
- pos: SeekFrom,
- ) -> Poll<io::Result<u64>> {
- unreachable!()
- }
- }
+ This trait is a re-export of [`futures::io::AsyncSeek`] and is an async version of
+ [`std::io::Seek`].
 
- impl<T: Seek + Unpin + ?Sized> Seek for &mut T {
- fn poll_seek(
- self: Pin<&mut Self>,
- cx: &mut Context<'_>,
- pos: SeekFrom,
- ) -> Poll<io::Result<u64>> {
- unreachable!()
- }
- }
+ The [provided methods] do not really exist in the trait itself, but they become
+ available when the prelude is imported:
+
+ ```
+ # #[allow(unused_imports)]
+ use async_std::prelude::*;
+ ```
+
+ [`std::io::Seek`]: https://doc.rust-lang.org/std/io/trait.Seek.html
+ [`futures::io::AsyncSeek`]:
+ https://docs.rs/futures-preview/0.3.0-alpha.17/futures/io/trait.AsyncSeek.html
+ [provided methods]: #provided-methods
+ "#]
+ pub trait Seek [SeekExt: futures_io::AsyncSeek] {
+ #[doc = r#"
+ Attempt to seek to an offset, in bytes, in a stream.
+ "#]
+ fn poll_seek(
+ self: Pin<&mut Self>,
+ cx: &mut Context<'_>,
+ pos: SeekFrom,
+ ) -> Poll<io::Result<u64>>;
+
+ #[doc = r#"
+ Seeks to a new position in a byte stream.
+
+ Returns the new position in the byte stream.
+
+ A seek beyond the end of stream is allowed, but behavior is defined by the
+ implementation.
+
+ # Examples
+
+ ```no_run
+ # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+ #
+ use async_std::fs::File;
+ use async_std::io::SeekFrom;
+ use async_std::prelude::*;
 
- impl<P> Seek for Pin<P>
+ let mut file = File::open("a.txt").await?;
+
+ let file_len = file.seek(SeekFrom::End(0)).await?;
+ #
+ # Ok(()) }) }
+ ```
+ "#]
+ fn seek(
+ &mut self,
+ pos: SeekFrom,
+ ) -> impl Future<Output = io::Result<u64>> [SeekFuture<'_, Self>]
  where
- P: DerefMut + Unpin,
- <P as Deref>::Target: Seek,
+ Self: Unpin,
  {
- fn poll_seek(
- self: Pin<&mut Self>,
- cx: &mut Context<'_>,
- pos: SeekFrom,
- ) -> Poll<io::Result<u64>> {
- unreachable!()
- }
+ SeekFuture { seeker: self, pos }
  }
- } else {
- pub use futures_io::AsyncSeek as Seek;
  }
-}
 
-#[doc(hidden)]
-pub trait SeekExt: futures_io::AsyncSeek {
- fn seek(&mut self, pos: SeekFrom) -> SeekFuture<'_, Self>
+ impl<T: Seek + Unpin + ?Sized> Seek for Box<T> {
+ fn poll_seek(
+ self: Pin<&mut Self>,
+ cx: &mut Context<'_>,
+ pos: SeekFrom,
+ ) -> Poll<io::Result<u64>> {
+ unreachable!("this impl only appears in the rendered docs")
+ }
+ }
+
+ impl<T: Seek + Unpin + ?Sized> Seek for &mut T {
+ fn poll_seek(
+ self: Pin<&mut Self>,
+ cx: &mut Context<'_>,
+ pos: SeekFrom,
+ ) -> Poll<io::Result<u64>> {
+ unreachable!("this impl only appears in the rendered docs")
+ }
+ }
+
+ impl<P> Seek for Pin<P>
  where
- Self: Unpin,
+ P: DerefMut + Unpin,
+ <P as Deref>::Target: Seek,
  {
- SeekFuture { seeker: self, pos }
+ fn poll_seek(
+ self: Pin<&mut Self>,
+ cx: &mut Context<'_>,
+ pos: SeekFrom,
+ ) -> Poll<io::Result<u64>> {
+ unreachable!("this impl only appears in the rendered docs")
+ }
  }
 }
 
-impl<T: futures_io::AsyncSeek + ?Sized> SeekExt for T {}
-
 #[doc(hidden)]
 #[allow(missing_debug_implementations)]
 pub struct SeekFuture<'a, T: Unpin + ?Sized> {