Update `std::io::{pipe, PipeReader, PipeWriter}` docs the new location

Also create a section "Platform-specific behavior", don't hide required
imports for code examples.

1 files changed, 20 insertions, 16 deletions

diff --git a/library/std/src/io/pipe.rs b/library/std/src/io/pipe.rs
index cd33294b271..266c7bc9638 100644
--- a/library/std/src/io/pipe.rs
+++ b/library/std/src/io/pipe.rs
@@ -1,7 +1,7 @@
 use crate::io;
 use crate::sys::anonymous_pipe::{AnonPipe, pipe as pipe_inner};
 
-/// Create an anonymous pipe that is close-on-exec and blocking.
+/// Create an anonymous pipe.
 ///
 /// # Behavior
 ///
@@ -22,6 +22,13 @@ use crate::sys::anonymous_pipe::{AnonPipe, pipe as pipe_inner};
 ///   interleaving.
 /// * Portable applications cannot assume any atomicity of messages larger than a single byte.
 ///
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `pipe` function on Unix and the
+/// `CreatePipe` function on Windows.
+///
+/// Note that this [may change in the future][changes].
+///
 /// # Capacity
 ///
 /// Pipe capacity is platform dependent. To quote the Linux [man page]:
@@ -37,10 +44,10 @@ use crate::sys::anonymous_pipe::{AnonPipe, pipe as pipe_inner};
 /// # #[cfg(miri)] fn main() {}
 /// # #[cfg(not(miri))]
 /// # fn main() -> std::io::Result<()> {
-/// # use std::process::Command;
-/// # use std::io::{Read, Write};
-/// let (ping_rx, mut ping_tx) = std::io::pipe()?;
-/// let (mut pong_rx, pong_tx) = std::io::pipe()?;
+/// use std::process::Command;
+/// use std::io::{pipe, Read, Write};
+/// let (ping_rx, mut ping_tx) = pipe()?;
+/// let (mut pong_rx, pong_tx) = pipe()?;
 ///
 /// // Spawn a process that echoes its input.
 /// let mut echo_server = Command::new("cat").stdin(ping_rx).stdout(pong_tx).spawn()?;
@@ -58,6 +65,7 @@ use crate::sys::anonymous_pipe::{AnonPipe, pipe as pipe_inner};
 /// # Ok(())
 /// # }
 /// ```
+/// [changes]: io#platform-specific-behavior
 /// [man page]: https://man7.org/linux/man-pages/man7/pipe.7.html
 #[unstable(feature = "anonymous_pipe", issue = "127154")]
 #[inline]
@@ -85,15 +93,15 @@ impl PipeReader {
     /// # #[cfg(miri)] fn main() {}
     /// # #[cfg(not(miri))]
     /// # fn main() -> std::io::Result<()> {
-    /// # use std::fs;
-    /// # use std::io::Write;
-    /// # use std::process::Command;
+    /// use std::fs;
+    /// use std::io::{pipe, Write};
+    /// use std::process::Command;
     /// const NUM_SLOT: u8 = 2;
     /// const NUM_PROC: u8 = 5;
     /// const OUTPUT: &str = "work.txt";
     ///
     /// let mut jobs = vec![];
-    /// let (reader, mut writer) = std::io::pipe()?;
+    /// let (reader, mut writer) = pipe()?;
     ///
     /// // Write NUM_SLOT characters the pipe.
     /// writer.write_all(&[b'|'; NUM_SLOT as usize])?;
@@ -145,9 +153,9 @@ impl PipeWriter {
     /// # #[cfg(miri)] fn main() {}
     /// # #[cfg(not(miri))]
     /// # fn main() -> std::io::Result<()> {
-    /// # use std::process::Command;
-    /// # use std::io::Read;
-    /// let (mut reader, writer) = std::io::pipe()?;
+    /// use std::process::Command;
+    /// use std::io::{pipe, Read};
+    /// let (mut reader, writer) = pipe()?;
     ///
     /// // Spawn a process that writes to stdout and stderr.
     /// let mut peer = Command::new("bash")
@@ -224,11 +232,9 @@ impl io::Write for &PipeWriter {
     fn flush(&mut self) -> io::Result<()> {
         Ok(())
     }
-
     fn write_vectored(&mut self, bufs: &[io::IoSlice<'_>]) -> io::Result<usize> {
         self.0.write_vectored(bufs)
     }
-
     #[inline]
     fn is_write_vectored(&self) -> bool {
         self.0.is_write_vectored()
@@ -244,11 +250,9 @@ impl io::Write for PipeWriter {
     fn flush(&mut self) -> io::Result<()> {
         Ok(())
     }
-
     fn write_vectored(&mut self, bufs: &[io::IoSlice<'_>]) -> io::Result<usize> {
         self.0.write_vectored(bufs)
     }
-
     #[inline]
     fn is_write_vectored(&self) -> bool {
         self.0.is_write_vectored()