io: add SyncIoBridge cross-references to copy and copy_buf (#7798)

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
     ///

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
     ///