net: add documentation to try_read() for zero-length buffers (#4937)

tokio/src/net/tcp/split.rs

@@ -190,8 +190,12 @@ impl ReadHalf<'_> {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     pub fn try_read(&self, buf: &mut [u8]) -> io::Result<usize> {
         self.0.try_read(buf)

tokio/src/net/tcp/split_owned.rs

@@ -245,8 +245,12 @@ impl OwnedReadHalf {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     pub fn try_read(&self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.try_read(buf)

tokio/src/net/tcp/stream.rs

@@ -547,8 +547,12 @@ impl TcpStream {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     ///
     /// # Examples

tokio/src/net/unix/split.rs

@@ -100,8 +100,12 @@ impl ReadHalf<'_> {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     pub fn try_read(&self, buf: &mut [u8]) -> io::Result<usize> {
         self.0.try_read(buf)

tokio/src/net/unix/split_owned.rs

@@ -155,8 +155,12 @@ impl OwnedReadHalf {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     pub fn try_read(&self, buf: &mut [u8]) -> io::Result<usize> {
         self.inner.try_read(buf)

tokio/src/net/unix/stream.rs

@@ -239,8 +239,12 @@ impl UnixStream {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the stream's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the stream is not ready to read data
+    ///
+    /// 1. The stream's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the stream is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     ///
     /// # Examples

tokio/src/net/windows/named_pipe.rs

@@ -403,8 +403,12 @@ impl NamedPipeServer {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the pipe's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the pipe is not ready to read data
+    ///
+    /// 1. The pipe's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the pipe is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     ///
     /// # Examples
@@ -1143,8 +1147,12 @@ impl NamedPipeClient {
     /// # Return
     ///
     /// If data is successfully read, `Ok(n)` is returned, where `n` is the
-    /// number of bytes read. `Ok(0)` indicates the pipe's read half is closed
+    /// number of bytes read. If `n` is `0`, then it can indicate one of two scenarios:
-    /// and will no longer yield data. If the pipe is not ready to read data
+    ///
+    /// 1. The pipe's read half is closed and will no longer yield data.
+    /// 2. The specified buffer was 0 bytes in length.
+    ///
+    /// If the pipe is not ready to read data,
     /// `Err(io::ErrorKind::WouldBlock)` is returned.
     ///
     /// # Examples