Improve documents for splice modules

Author: oech3

src/uucore/src/lib/features/buf_copy/linux.rs

@@ -26,6 +26,7 @@ pub fn copy_stream(
     if crate::pipes::splice_unbounded_auto(src, dest)? {
         // If the splice() call failed, fall back on writing "without buffering", or order of output would be wrong
         // unrelated for cp /dev/stdin since cp does not have multiple input? <https://github.com/uutils/coreutils/issues/5186>
+        // RawWriter also removes io::copy's specialization
         std::io::copy(src, &mut crate::io::RawWriter(dest))?;
     }
     Ok(())

src/uucore/src/lib/features/pipes.rs

@@ -3,7 +3,7 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
-//! Thin zero-copy-related wrappers around functions.
+//! Zero-copy-related functions.
 
 #[cfg(any(target_os = "linux", target_os = "android"))]
 use crate::io::{RawReader, RawWriter};
@@ -46,10 +46,8 @@ pub fn pipe<const SIZE_REQUIRED: bool>(s: usize) -> std::io::Result<(PipeReader,
 /// Up to `len` bytes are moved from `source` to `target`. Returns the number
 /// of successfully moved bytes.
 ///
-/// At least one of `source` and `target` must be some sort of pipe.
-/// To get around this requirement, consider splicing from your source into
-/// a [`pipe`] and then from the pipe into your target (with `splice_exact`):
-/// this is still very efficient.
+/// splice fails if both of `source` and `target` are not pipe. Consider using
+/// splice_unbounded_broker or splice_unbounded_auto in the case.
 #[inline]
 #[cfg(any(target_os = "linux", target_os = "android"))]
 pub fn splice(source: &impl AsFd, target: &impl AsFd, len: usize) -> rustix::io::Result<usize> {
@@ -102,8 +100,8 @@ pub fn splice_unbounded(source: &impl AsFd, dest: &mut impl AsFd) -> rustix::io:
 
 /// force-splice source to dest even both of them are not pipe via broker pipe
 /// returns Ok(Ok(())) if splice succeeds
-/// returns Ok(Err()) if splice failed, but you can fallback to read/write
-/// returns std::io::Result if splice from broker failed and read/write fallback from broker failed
+/// returns Ok(Err(())) if splice failed, but you can fallback to read/write
+/// returns Err(e) if splice from broker failed and read/write fallback from broker failed
 ///
 /// Thus, ?.is_err() returns serious error at early stage and checks that you can fallback
 /// This should not be used if one of them are pipe to save resources
@@ -163,7 +161,7 @@ pub fn splice_unbounded_auto(source: &impl AsFd, dest: &mut impl AsFd) -> std::i
     Ok(fallback)
 }
 
-/// splice `n` bytes with safe read/write fallback
+/// splice `n` bytes with read/write fallback
 /// return actually sent bytes
 #[inline]
 #[cfg(any(target_os = "linux", target_os = "android"))]