Improve documentation on process::Child.std* fields

As a relative beginner, it took a while for me to figure out I could just steal the references to avoid partially moving the child and thus retain ability to call functions on it (and store it in structs etc).

1 files changed, 24 insertions, 3 deletions

diff --git a/library/std/src/process.rs b/library/std/src/process.rs
index 4ba1940fd0e..409a9450186 100644
--- a/library/std/src/process.rs
+++ b/library/std/src/process.rs
@@ -170,17 +170,38 @@ pub struct Child {
     handle: imp::Process,
 
     /// The handle for writing to the child's standard input (stdin), if it has
-    /// been captured.
+    /// been captured. To avoid partially moving
+    /// the `child` and thus blocking yourself from calling
+    /// functions on `child` while using `stdin`,
+    /// you might find it helpful:
+    ///
+    /// ```compile_fail,E0425
+    /// let stdin = child.stdin.take().unwrap();
+    /// ```
     #[stable(feature = "process", since = "1.0.0")]
     pub stdin: Option<ChildStdin>,
 
     /// The handle for reading from the child's standard output (stdout), if it
-    /// has been captured.
+    /// has been captured. You might find it helpful to do
+    ///
+    /// ```compile_fail,E0425
+    /// let stdout = child.stdout.take().unwrap();
+    /// ```
+    ///
+    /// to avoid partially moving the `child` and thus blocking yourself from calling
+    /// functions on `child` while using `stdout`.
     #[stable(feature = "process", since = "1.0.0")]
     pub stdout: Option<ChildStdout>,
 
     /// The handle for reading from the child's standard error (stderr), if it
-    /// has been captured.
+    /// has been captured. You might find it helpful to do
+    ///
+    /// ```compile_fail,E0425
+    /// let stderr = child.stderr.take().unwrap();
+    /// ```
+    ///
+    /// to avoid partially moving the `child` and thus blocking yourself from calling
+    /// functions on `child` while using `stderr`.
     #[stable(feature = "process", since = "1.0.0")]
     pub stderr: Option<ChildStderr>,
 }