From 54a394696fd6980a3840a2e5b0022ae359f47e05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Marcos?= <marcospb19@hotmail.com>
Date: Thu, 23 Mar 2023 12:19:51 -0300
Subject: [PATCH] io: add details to docs of `tokio::io::copy[_buf]` (#5575)

---
 tokio/src/io/util/copy.rs     | 10 +++++++++-
 tokio/src/io/util/copy_buf.rs |  8 +++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/tokio/src/io/util/copy.rs b/tokio/src/io/util/copy.rs
index 47dad89c76c..55861244fab 100644
--- a/tokio/src/io/util/copy.rs
+++ b/tokio/src/io/util/copy.rs
@@ -153,14 +153,22 @@ cfg_io_util! {
     ///
     /// This function returns a future that will continuously read data from
     /// `reader` and then write it into `writer` in a streaming fashion until
-    /// `reader` returns EOF.
+    /// `reader` returns EOF or fails.
     ///
     /// On success, the total number of bytes that were copied from `reader` to
     /// `writer` is returned.
     ///
     /// This is an asynchronous version of [`std::io::copy`][std].
     ///
+    /// A heap-allocated copy buffer with 8 KB is created to take data from the
+    /// reader to the writer, check [`copy_buf`] if you want an alternative for
+    /// [`AsyncBufRead`]. You can use `copy_buf` with [`BufReader`] to change the
+    /// buffer capacity.
+    ///
     /// [std]: std::io::copy
+    /// [`copy_buf`]: crate::io::copy_buf
+    /// [`AsyncBufRead`]: crate::io::AsyncBufRead
+    /// [`BufReader`]: crate::io::BufReader
     ///
     /// # Errors
     ///
diff --git a/tokio/src/io/util/copy_buf.rs b/tokio/src/io/util/copy_buf.rs
index 6831580b407..c23fc9a2b4c 100644
--- a/tokio/src/io/util/copy_buf.rs
+++ b/tokio/src/io/util/copy_buf.rs
@@ -24,11 +24,17 @@ cfg_io_util! {
     ///
     /// This function returns a future that will continuously read data from
     /// `reader` and then write it into `writer` in a streaming fashion until
-    /// `reader` returns EOF.
+    /// `reader` returns EOF or fails.
     ///
     /// On success, the total number of bytes that were copied from `reader` to
     /// `writer` is returned.
     ///
+    /// This is a [`tokio::io::copy`] alternative for [`AsyncBufRead`] readers
+    /// with no extra buffer allocation, since [`AsyncBufRead`] allow access
+    /// to the reader's inner buffer.
+    ///
+    /// [`tokio::io::copy`]: crate::io::copy
+    /// [`AsyncBufRead`]: crate::io::AsyncBufRead
     ///
     /// # Errors
     ///