Simplify the first trait in extension_trait.

The body and doc comment are no longer used.

Author: nnethercote

src/future/future/mod.rs

@@ -21,110 +21,7 @@ cfg_unstable_default! {
 }
 
 extension_trait! {
-    #[doc = r#"
-        A future represents an asynchronous computation.
-
-        A future is a value that may not have finished computing yet. This kind of
-        "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
-        final value. This method does not block if the value is not ready. Instead,
-        the current task is scheduled to be woken up when it's possible to make
-        further progress by `poll`ing again. The `context` passed to the `poll`
-        method can provide a [`Waker`], which is a handle for waking up the current
-        task.
-
-        When using a future, you generally won't call `poll` directly, but instead
-        `.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#"
-            The type of value produced on completion.
-        "#]
-        type Output;
-
-        #[doc = r#"
-            Attempt to resolve the future to a final value, registering
-            the current task for wakeup if the value is not yet available.
-
-            # Return value
-
-            This function returns:
-
-            - [`Poll::Pending`] if the future is not ready yet
-            - [`Poll::Ready(val)`] with the result `val` of this future if it
-              finished successfully.
-
-            Once a future has finished, clients should not `poll` it again.
-
-            When a future is not ready yet, `poll` returns `Poll::Pending` and
-            stores a clone of the [`Waker`] copied from the current [`Context`].
-            This [`Waker`] is then woken once the future can make progress.
-            For example, a future waiting for a socket to become
-            readable would call `.clone()` on the [`Waker`] and store it.
-            When a signal arrives elsewhere indicating that the socket is readable,
-            [`Waker::wake`] is called and the socket future's task is awoken.
-            Once a task has been woken up, it should attempt to `poll` the future
-            again, which may or may not produce a final value.
-
-            Note that on multiple calls to `poll`, only the [`Waker`] from the
-            [`Context`] passed to the most recent call should be scheduled to
-            receive a wakeup.
-
-            # Runtime characteristics
-
-            Futures alone are *inert*; they must be *actively* `poll`ed to make
-            progress, meaning that each time the current task is woken up, it should
-            actively re-`poll` pending futures that it still has an interest in.
-
-            The `poll` function is not called repeatedly in a tight loop -- instead,
-            it should only be called when the future indicates that it is ready to
-            make progress (by calling `wake()`). If you're familiar with the
-            `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures
-            typically do *not* suffer the same problems of "all wakeups must poll
-            all events"; they are more like `epoll(4)`.
-
-            An implementation of `poll` should strive to return quickly, and should
-            not block. Returning quickly prevents unnecessarily clogging up
-            threads or event loops. If it is known ahead of time that a call to
-            `poll` may end up taking awhile, the work should be offloaded to a
-            thread pool (or something similar) to ensure that `poll` can return
-            quickly.
-
-            # Panics
-
-            Once a future has completed (returned `Ready` from `poll`), calling its
-            `poll` method again may panic, block forever, or cause other kinds of
-            problems; the `Future` trait places no requirements on the effects of
-            such a call. However, as the `poll` method is not marked `unsafe`,
-            Rust's usual rules apply: calls must never cause undefined behavior
-            (memory corruption, incorrect use of `unsafe` functions, or the like),
-            regardless of the future's state.
-
-            [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending
-            [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready
-            [`Context`]: ../task/struct.Context.html
-            [`Waker`]: ../task/struct.Waker.html
-            [`Waker::wake`]: ../task/struct.Waker.html#method.wake
-        "#]
-        fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output>;
-    }
+    pub trait Future {}
 
     #[doc = r#"
         Extension methods for [`Future`].

src/io/buf_read/mod.rs

@@ -16,51 +16,7 @@ use crate::io;
 use crate::task::{Context, Poll};
 
 extension_trait! {
-    #[doc = r#"
-        Allows reading from a buffered byte stream.
-
-        This trait is a re-export of [`futures::io::AsyncBufRead`] and is an async version of
-        [`std::io::BufRead`].
-
-        The [provided methods] do not really exist in the trait itself, but they become
-        available when [`BufReadExt`] from the [prelude] is imported:
-
-        ```
-        # #[allow(unused_imports)]
-        use async_std::io::prelude::*;
-        ```
-
-        [`std::io::BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
-        [`futures::io::AsyncBufRead`]:
-        https://docs.rs/futures/0.3/futures/io/trait.AsyncBufRead.html
-        [provided methods]: #provided-methods
-        [`BufReadExt`]: ../io/prelude/trait.BufReadExt.html
-        [prelude]: ../prelude/index.html
-    "#]
-    pub trait BufRead {
-        #[doc = r#"
-            Returns the contents of the internal buffer, filling it with more data from the
-            inner reader if it is empty.
-
-            This function is a lower-level call. It needs to be paired with the [`consume`]
-            method to function properly. When calling this method, none of the contents will be
-            "read" in the sense that later calling `read` may return the same contents. As
-            such, [`consume`] must be called with the number of bytes that are consumed from
-            this buffer to ensure that the bytes are never returned twice.
-
-            [`consume`]: #tymethod.consume
-
-            An empty buffer returned indicates that the stream has reached EOF.
-        "#]
-        // TODO: write a proper doctest with `consume`
-        fn poll_fill_buf(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<&[u8]>>;
-
-        #[doc = r#"
-            Tells this buffer that `amt` bytes have been consumed from the buffer, so they
-            should no longer be returned in calls to `read`.
-        "#]
-        fn consume(self: Pin<&mut Self>, amt: usize);
-    }
+    pub trait BufRead {}
 
     #[doc = r#"
         Extension methods for [`BufRead`].

src/io/read/mod.rs

@@ -22,49 +22,7 @@ pub use chain::Chain;
 pub use take::Take;
 
 extension_trait! {
-    #[doc = r#"
-        Allows reading from a byte stream.
-
-        This trait is a re-export of [`futures::io::AsyncRead`] and is an async version of
-        [`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 [`ReadExt`] from the [prelude] is imported:
-
-        ```
-        # #[allow(unused_imports)]
-        use async_std::prelude::*;
-        ```
-
-        [`std::io::Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
-        [`futures::io::AsyncRead`]:
-        https://docs.rs/futures/0.3/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#"
-            Attempt to read from the `AsyncRead` into `buf`.
-        "#]
-        fn poll_read(
-            self: Pin<&mut Self>,
-            cx: &mut Context<'_>,
-            buf: &mut [u8],
-        ) -> Poll<io::Result<usize>>;
-
-        #[doc = r#"
-            Attempt to read from the `AsyncRead` into `bufs` using vectored IO operations.
-        "#]
-        fn poll_read_vectored(
-            self: Pin<&mut Self>,
-            cx: &mut Context<'_>,
-            bufs: &mut [IoSliceMut<'_>],
-        ) -> Poll<io::Result<usize>> {
-            unreachable!("this impl only appears in the rendered docs")
-        }
-    }
+    pub trait Read {}
 
     #[doc = r#"
         Extension methods for [`Read`].

src/io/seek/mod.rs

@@ -5,37 +5,7 @@ use seek::SeekFuture;
 use crate::io::SeekFrom;
 
 extension_trait! {
-    #[doc = r#"
-        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 [`SeekExt`] 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/0.3/futures/io/trait.AsyncSeek.html
-        [provided methods]: #provided-methods
-        [`SeekExt`]: ../io/prelude/trait.SeekExt.html
-        [prelude]: ../prelude/index.html
-    "#]
-    pub trait Seek {
-        #[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>>;
-    }
+    pub trait Seek {}
 
     #[doc = r#"
         Extension methods for [`Seek`].

src/io/write/mod.rs

@@ -13,63 +13,7 @@ use write_vectored::WriteVectoredFuture;
 use crate::io::{self, IoSlice};
 
 extension_trait! {
-    #[doc = r#"
-        Allows writing to a byte stream.
-
-        This trait is a re-export of [`futures::io::AsyncWrite`] and is an async version of
-        [`std::io::Write`].
-
-        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
-        [`WriteExt`] from the [prelude] is imported:
-
-        ```
-        # #[allow(unused_imports)]
-        use async_std::prelude::*;
-        ```
-
-        [`std::io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
-        [`futures::io::AsyncWrite`]:
-        https://docs.rs/futures/0.3/futures/io/trait.AsyncWrite.html
-        [`poll_write`]: #tymethod.poll_write
-        [`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#"
-            Attempt to write bytes from `buf` into the object.
-        "#]
-        fn poll_write(
-            self: Pin<&mut Self>,
-            cx: &mut Context<'_>,
-            buf: &[u8],
-        ) -> Poll<io::Result<usize>>;
-
-        #[doc = r#"
-            Attempt to write bytes from `bufs` into the object using vectored IO operations.
-        "#]
-        fn poll_write_vectored(
-            self: Pin<&mut Self>,
-            cx: &mut Context<'_>,
-            bufs: &[IoSlice<'_>]
-        ) -> Poll<io::Result<usize>> {
-            unreachable!("this impl only appears in the rendered docs")
-        }
-
-        #[doc = r#"
-            Attempt to flush the object, ensuring that any buffered data reach
-            their destination.
-        "#]
-        fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
-
-        #[doc = r#"
-            Attempt to close the object.
-        "#]
-        fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
-    }
+    pub trait Write {}
 
     #[doc = r#"
         Extension methods for [`Write`].