From 4bc2a15d28554426a500ce73be969ecd9ed6dd89 Mon Sep 17 00:00:00 2001
From: Andrea Bozzo <andreabozzo92@gmail.com>
Date: Mon, 29 Dec 2025 15:29:56 +0100
Subject: [PATCH] io: add `SyncIoBridge` cross-references to `copy` and
 `copy_buf` (#7798)

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

diff --git a/tokio/src/io/util/copy.rs b/tokio/src/io/util/copy.rs
index f2dbd7067..ac7eb891d 100644
--- a/tokio/src/io/util/copy.rs
+++ b/tokio/src/io/util/copy.rs
@@ -241,10 +241,18 @@ cfg_io_util! {
     /// [`AsyncBufRead`]. You can use `copy_buf` with [`BufReader`] to change the
     /// buffer capacity.
     ///
+    /// # When to use async alternatives instead of `SyncIoBridge`
+    ///
+    /// If you are looking to use [`std::io::copy`] with a synchronous consumer
+    /// (like a `hasher` or compressor), consider using async alternatives instead of
+    /// wrapping the reader with [`SyncIoBridge`].
+    /// See the [`SyncIoBridge`] documentation for detailed examples and guidance.
+    ///
     /// [std]: std::io::copy
     /// [`copy_buf`]: crate::io::copy_buf
     /// [`AsyncBufRead`]: crate::io::AsyncBufRead
     /// [`BufReader`]: crate::io::BufReader
+    /// [`SyncIoBridge`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.SyncIoBridge.html
     ///
     /// # Errors
     ///
diff --git a/tokio/src/io/util/copy_buf.rs b/tokio/src/io/util/copy_buf.rs
index db622e94a..30b0837ff 100644
--- a/tokio/src/io/util/copy_buf.rs
+++ b/tokio/src/io/util/copy_buf.rs
@@ -33,8 +33,17 @@ cfg_io_util! {
     /// with no extra buffer allocation, since [`AsyncBufRead`] allow access
     /// to the reader's inner buffer.
     ///
+    /// # When to use async alternatives instead of `SyncIoBridge`
+    ///
+    /// If you are looking to use [`std::io::copy`] with a synchronous consumer
+    /// (like a `hasher` or compressor), consider using async alternatives instead of
+    /// wrapping the reader with [`SyncIoBridge`]. See the [`SyncIoBridge`]
+    /// documentation for detailed examples and guidance on hashing, compression,
+    /// and data parsing.
+    ///
     /// [`tokio::io::copy`]: crate::io::copy
     /// [`AsyncBufRead`]: crate::io::AsyncBufRead
+    /// [`SyncIoBridge`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.SyncIoBridge.html
     ///
     /// # Errors
     ///