From c78aa1884041520750d56c176a92df50d75f9e80 Mon Sep 17 00:00:00 2001 From: Evan Mesterhazy Date: Tue, 8 Jun 2021 18:28:17 -0400 Subject: [PATCH 1/3] doc: Clarify EOF condition for AsyncReadExt::read_buf --- tokio/src/io/util/async_read_ext.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 8ca0d3f1021..7a24d810d5b 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/tokio/src/io/util/async_read_ext.rs @@ -181,8 +181,9 @@ cfg_io_util! { /// # Return /// /// On a successful read, the number of read bytes is returned. If the - /// supplied buffer is not empty and the function returns `Ok(0)` then - /// the source has reached an "end-of-file" event. + /// remaining capacity of the supplied buffer is greater than 0 and + /// the function returns `Ok(0)` then the source has reached an + /// "end-of-file" event. /// /// # Errors /// From 82ea7fe2c3ef04e22dc64d273c40b0aace1589e4 Mon Sep 17 00:00:00 2001 From: Evan Mesterhazy Date: Wed, 9 Jun 2021 07:51:59 -0400 Subject: [PATCH 2/3] doc: Minor change to AsyncReadExt::read_buf to match read Squash into previous commit --- tokio/src/io/util/async_read_ext.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 7a24d810d5b..09e531286a0 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/tokio/src/io/util/async_read_ext.rs @@ -108,6 +108,8 @@ cfg_io_util! { /// This function does not provide any guarantees about whether it /// completes immediately or asynchronously /// + /// # Return + /// /// If the return value of this method is `Ok(n)`, then it must be /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates /// that the buffer `buf` has been filled in with `n` bytes of data from @@ -180,10 +182,16 @@ cfg_io_util! { /// /// # Return /// - /// On a successful read, the number of read bytes is returned. If the - /// remaining capacity of the supplied buffer is greater than 0 and - /// the function returns `Ok(0)` then the source has reached an - /// "end-of-file" event. + /// If the return value of this method is `Ok(n)`, then it must be + /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates + /// that the buffer `buf` has been filled in with `n` bytes of data from + /// this source. If `n` is `0`, then it can indicate one of two + /// scenarios: + /// + /// 1. This reader has reached its "end of file" and will likely no longer + /// be able to produce bytes. Note that this does not mean that the + /// reader will *always* no longer be able to produce bytes. + /// 2. The buffer specified had a remaining capacity of zero. /// /// # Errors /// From 9da0d220aadbffc0f08d944955b8d042518734d4 Mon Sep 17 00:00:00 2001 From: Evan Mesterhazy Date: Wed, 9 Jun 2021 08:08:25 -0400 Subject: [PATCH 3/3] doc: Fix AsyncReadExt::read_mut docstring --- tokio/src/io/util/async_read_ext.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 09e531286a0..878676fca94 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/tokio/src/io/util/async_read_ext.rs @@ -182,11 +182,9 @@ cfg_io_util! { /// /// # Return /// - /// If the return value of this method is `Ok(n)`, then it must be - /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates - /// that the buffer `buf` has been filled in with `n` bytes of data from - /// this source. If `n` is `0`, then it can indicate one of two - /// scenarios: + /// A nonzero `n` value indicates that the buffer `buf` has been filled + /// in with `n` bytes of data from this source. If `n` is `0`, then it + /// can indicate one of two scenarios: /// /// 1. This reader has reached its "end of file" and will likely no longer /// be able to produce bytes. Note that this does not mean that the