Rollup merge of rust-lang#157360 - sanidhyasin:document-command-spawn-errors, r=LawnGnome

Document error conditions for `Command::{spawn, output, status}`

Fixes rust-lang#150361.

`Command::spawn`, `Command::output`, and `Command::status` all return `io::Result`, but the docs never explain *why* they can fail, and they do not mention the (easy to get wrong) distinction between a failure to spawn and a child that runs but exits unsuccessfully or is killed by a signal.

This adds an `# Errors` section to each method:

- **`spawn`** describes the common reasons spawning fails — the program not being found, lacking permission to execute it (e.g. not executable, or blocked by a policy such as `seccomp`), and the OS being unable to create the process due to resource exhaustion. It also clarifies that an error is only returned for failures *while spawning*; once the child has started, anything that happens to it (including signals) is reported through its `ExitStatus`.
- **`output`** and **`status`** refer back to `spawn` for the spawn failures, and explicitly note that a child which exits unsuccessfully or is terminated by a signal is **not** an error — they still return `Ok`, with the outcome reflected in the resulting `ExitStatus`.

The error conditions and the signal/`ExitStatus` behavior were confirmed by `@bjorn3` in the issue discussion.

Docs-only change; no code blocks were added or modified, and all intra-doc links (`io::Error`, `ExitStatus`, `Output`, `spawn`) follow link patterns already used in this module.

r? libs

Author: JonathanBrouwer

library/std/src/process.rs

@@ -1062,6 +1062,26 @@ impl Command {
     ///
     /// By default, stdin, stdout and stderr are inherited from the parent.
     ///
+    /// # Errors
+    ///
+    /// This method returns an [`io::Error`] if the child process could not be
+    /// spawned. Common reasons include:
+    ///
+    /// * the program could not be found (for example, it does not exist, or,
+    ///   when given a bare name, it is not present in the `PATH`);
+    /// * the current process does not have permission to execute the program
+    ///   (for example, the file is not marked executable, or execution is
+    ///   denied by a security policy such as `seccomp`);
+    /// * the operating system could not create the new process because of
+    ///   resource exhaustion (for example, a limit on the number of processes
+    ///   was reached).
+    ///
+    /// An error is only returned for failures that occur while the child is
+    /// being spawned. Once the child has started successfully, anything that
+    /// happens to it afterwards — including being terminated by a signal — is
+    /// reported through its [`ExitStatus`] rather than as an error from the
+    /// spawning method.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -1084,6 +1104,20 @@ impl Command {
     /// attempt by the child process to read from the stdin stream will result
     /// in the stream immediately closing.
     ///
+    /// # Errors
+    ///
+    /// Like [`spawn`], this method returns an [`io::Error`] if the child
+    /// process could not be spawned; see [`spawn`] for the common reasons. It
+    /// may also return an error if reading the child's output or waiting on the
+    /// child fails.
+    ///
+    /// Note that this method does **not** return an error if the child runs and
+    /// then exits unsuccessfully, or is terminated by a signal. In those cases
+    /// it still returns [`Ok`], and the outcome is reflected in the
+    /// [`ExitStatus`] stored in the returned [`Output`].
+    ///
+    /// [`spawn`]: Command::spawn
+    ///
     /// # Examples
     ///
     /// ```should_panic
@@ -1111,6 +1145,19 @@ impl Command {
     ///
     /// By default, stdin, stdout and stderr are inherited from the parent.
     ///
+    /// # Errors
+    ///
+    /// Like [`spawn`], this method returns an [`io::Error`] if the child
+    /// process could not be spawned; see [`spawn`] for the common reasons. It
+    /// may also return an error if waiting on the child fails.
+    ///
+    /// Note that this method does **not** return an error if the child runs and
+    /// then exits unsuccessfully, or is terminated by a signal. In those cases
+    /// it still returns [`Ok`], and the outcome is reflected in the returned
+    /// [`ExitStatus`].
+    ///
+    /// [`spawn`]: Command::spawn
+    ///
     /// # Examples
     ///
     /// ```should_panic