diff options
author | Alice Ryhl <alice@ryhl.io> | 2020-04-24 00:11:49 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-04-23 15:11:49 -0700 |
commit | 9bcb50660e2d9de26a4373aaf4ab8f324c8ebbe8 (patch) | |
tree | 744803b55ae681aeae2f6ba02c3f939744bdce34 /tokio/src/net | |
parent | a3aab864d776692bc53357b115c8b06d789c630b (diff) |
docs: make it easier to discover extension traits (#2434)
Refs: #2307
Diffstat (limited to 'tokio/src/net')
-rw-r--r-- | tokio/src/net/tcp/split.rs | 31 | ||||
-rw-r--r-- | tokio/src/net/tcp/split_owned.rs | 21 | ||||
-rw-r--r-- | tokio/src/net/tcp/stream.rs | 22 |
3 files changed, 68 insertions, 6 deletions
diff --git a/tokio/src/net/tcp/split.rs b/tokio/src/net/tcp/split.rs index 39dca996..469056ac 100644 --- a/tokio/src/net/tcp/split.rs +++ b/tokio/src/net/tcp/split.rs @@ -19,14 +19,32 @@ use std::net::Shutdown; use std::pin::Pin; use std::task::{Context, Poll}; -/// Read half of a `TcpStream`. +/// Read half of a [`TcpStream`], created by [`split`]. +/// +/// Reading from a `ReadHalf` is usually done using the convenience methods found on the +/// [`AsyncReadExt`] trait. Examples import this trait through [the prelude]. +/// +/// [`TcpStream`]: TcpStream +/// [`split`]: TcpStream::split() +/// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt +/// [the prelude]: crate::prelude #[derive(Debug)] pub struct ReadHalf<'a>(&'a TcpStream); -/// Write half of a `TcpStream`. +/// Write half of a [`TcpStream`], created by [`split`]. /// -/// Note that in the `AsyncWrite` implemenation of this type, `poll_shutdown` will +/// Note that in the [`AsyncWrite`] implemenation of this type, [`poll_shutdown`] will /// shut down the TCP stream in the write direction. +/// +/// Writing to an `OwnedWriteHalf` is usually done using the convenience methods found +/// on the [`AsyncWriteExt`] trait. Examples import this trait through [the prelude]. +/// +/// [`TcpStream`]: TcpStream +/// [`split`]: TcpStream::split() +/// [`AsyncWrite`]: trait@crate::io::AsyncWrite +/// [`poll_shutdown`]: fn@crate::io::AsyncWrite::poll_shutdown +/// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt +/// [the prelude]: crate::prelude #[derive(Debug)] pub struct WriteHalf<'a>(&'a TcpStream); @@ -74,6 +92,8 @@ impl ReadHalf<'_> { /// /// See the [`TcpStream::peek`] level documenation for more details. /// + /// [`TcpStream::peek`]: TcpStream::peek + /// /// # Examples /// /// ```no_run @@ -101,7 +121,10 @@ impl ReadHalf<'_> { /// } /// ``` /// - /// [`TcpStream::peek`]: TcpStream::peek + /// The [`read`] method is defined on the [`AsyncReadExt`] trait. + /// + /// [`read`]: fn@crate::io::AsyncReadExt::read + /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> { poll_fn(|cx| self.poll_peek(cx, buf)).await } diff --git a/tokio/src/net/tcp/split_owned.rs b/tokio/src/net/tcp/split_owned.rs index 908a39e2..ff82f6ed 100644 --- a/tokio/src/net/tcp/split_owned.rs +++ b/tokio/src/net/tcp/split_owned.rs @@ -23,8 +23,13 @@ use std::{fmt, io}; /// Owned read half of a [`TcpStream`], created by [`into_split`]. /// +/// Reading from an `OwnedReadHalf` is usually done using the convenience methods found +/// on the [`AsyncReadExt`] trait. Examples import this trait through [the prelude]. +/// /// [`TcpStream`]: TcpStream /// [`into_split`]: TcpStream::into_split() +/// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt +/// [the prelude]: crate::prelude #[derive(Debug)] pub struct OwnedReadHalf { inner: Arc<TcpStream>, @@ -32,13 +37,20 @@ pub struct OwnedReadHalf { /// Owned write half of a [`TcpStream`], created by [`into_split`]. /// -/// Note that in the `AsyncWrite` implemenation of this type, `poll_shutdown` will +/// Note that in the [`AsyncWrite`] implemenation of this type, [`poll_shutdown`] will /// shut down the TCP stream in the write direction. /// /// Dropping the write half will close the TCP stream in both directions. /// +/// Writing to an `OwnedWriteHalf` is usually done using the convenience methods found +/// on the [`AsyncWriteExt`] trait. Examples import this trait through [the prelude]. +/// /// [`TcpStream`]: TcpStream /// [`into_split`]: TcpStream::into_split() +/// [`AsyncWrite`]: trait@crate::io::AsyncWrite +/// [`poll_shutdown`]: fn@crate::io::AsyncWrite::poll_shutdown +/// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt +/// [the prelude]: crate::prelude #[derive(Debug)] pub struct OwnedWriteHalf { inner: Arc<TcpStream>, @@ -136,6 +148,8 @@ impl OwnedReadHalf { /// /// See the [`TcpStream::peek`] level documenation for more details. /// + /// [`TcpStream::peek`]: TcpStream::peek + /// /// # Examples /// /// ```no_run @@ -163,7 +177,10 @@ impl OwnedReadHalf { /// } /// ``` /// - /// [`TcpStream::peek`]: TcpStream::peek + /// The [`read`] method is defined on the [`AsyncReadExt`] trait. + /// + /// [`read`]: fn@crate::io::AsyncReadExt::read + /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> { poll_fn(|cx| self.poll_peek(cx, buf)).await } diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 03489152..ee44f810 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/tokio/src/net/tcp/stream.rs @@ -21,9 +21,16 @@ cfg_tcp! { /// A TCP stream can either be created by connecting to an endpoint, via the /// [`connect`] method, or by [accepting] a connection from a [listener]. /// + /// Reading and writing to a `TcpStream` is usually done using the + /// convenience methods found on the [`AsyncReadExt`] and [`AsyncWriteExt`] + /// traits. Examples import these traits through [the prelude]. + /// /// [`connect`]: method@TcpStream::connect /// [accepting]: method@super::TcpListener::accept /// [listener]: struct@super::TcpListener + /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt + /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt + /// [the prelude]: crate::prelude /// /// # Examples /// @@ -43,6 +50,11 @@ cfg_tcp! { /// Ok(()) /// } /// ``` + /// + /// The [`write_all`] method is defined on the [`AsyncWriteExt`] trait. + /// + /// [`write_all`]: fn@crate::io::AsyncWriteExt::write_all + /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt pub struct TcpStream { io: PollEvented<mio::net::TcpStream>, } @@ -77,6 +89,11 @@ impl TcpStream { /// Ok(()) /// } /// ``` + /// + /// The [`write_all`] method is defined on the [`AsyncWriteExt`] trait. + /// + /// [`write_all`]: fn@crate::io::AsyncWriteExt::write_all + /// [`AsyncWriteExt`]: trait@crate::io::AsyncWriteExt pub async fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<TcpStream> { let addrs = addr.to_socket_addrs().await?; @@ -303,6 +320,11 @@ impl TcpStream { /// Ok(()) /// } /// ``` + /// + /// The [`read`] method is defined on the [`AsyncReadExt`] trait. + /// + /// [`read`]: fn@crate::io::AsyncReadExt::read + /// [`AsyncReadExt`]: trait@crate::io::AsyncReadExt pub async fn peek(&mut self, buf: &mut [u8]) -> io::Result<usize> { poll_fn(|cx| self.poll_peek(cx, buf)).await } |