Rollup merge of #109272 - schneems:schneems/add-docs-to-command-env-methods, r=Amanieu

Add Command environment variable inheritance docs

The interaction between the environment variable methods can be confusing. Specifically `env_clear` and `remove_env` have a side effects not mentioned: they disable inheriting environment variables from the parent process. I wanted to fully document this behavior as well as explain relevant edge cases in each of the `Command` env methods.

This is further confused by the return of `get_envs` which will return key/None if `remove_env` has been used, but an empty iterator if `env_clear` has been called. Or a non-empty iterator if `env_clear` was called and later explicit mappings are added. Currently there is no way (that I'm able to find) of observing whether or not the internal `env_clear=true` been toggled on the `Command` struct via its public API.

Ultimately environment variable mappings can be in one of several states:

- Explicitly set value (via `envs` / `env`) will take precedence over parent mapping
- Not explicitly set, will inherit mapping from parent
- Explicitly removed via `remove_env`, this single mapping will not inherit from parent
- Implicitly removed via `env_clear`, no mappings will inherit from parent

I tried to represent this in the relevant sections of the docs.

This is my second-ever doc PR (whoop!). I'm happy to take specific or general doc feedback. Also happy to explain the logic behind any changes or additions I made.

1 files changed, 61 insertions, 15 deletions

diff --git a/library/std/src/process.rs b/library/std/src/process.rs
index 80d73084c4f..0ab72f7ea7a 100644
--- a/library/std/src/process.rs
+++ b/library/std/src/process.rs
@@ -652,10 +652,19 @@ impl Command {
         self
     }
 
-    /// Inserts or updates an environment variable mapping.
+    /// Inserts or updates an explicit environment variable mapping.
     ///
-    /// Note that environment variable names are case-insensitive (but case-preserving) on Windows,
-    /// and case-sensitive on all other platforms.
+    /// This method allows you to add an environment variable mapping to the spawned process or
+    /// overwrite a previously set value. You can use [`Command::envs`] to set multiple environment
+    /// variables simultaneously.
+    ///
+    /// Child processes will inherit environment variables from their parent process by default.
+    /// Environment variables explicitly set using [`Command::env`] take precedence over inherited
+    /// variables. You can disable environment variable inheritance entirely using
+    /// [`Command::env_clear`] or for a single key using [`Command::env_remove`].
+    ///
+    /// Note that environment variable names are case-insensitive (but
+    /// case-preserving) on Windows and case-sensitive on all other platforms.
     ///
     /// # Examples
     ///
@@ -679,7 +688,19 @@ impl Command {
         self
     }
 
-    /// Adds or updates multiple environment variable mappings.
+    /// Inserts or updates multiple explicit environment variable mappings.
+    ///
+    /// This method allows you to add multiple environment variable mappings to the spawned process
+    /// or overwrite previously set values. You can use [`Command::env`] to set a single environment
+    /// variable.
+    ///
+    /// Child processes will inherit environment variables from their parent process by default.
+    /// Environment variables explicitly set using [`Command::envs`] take precedence over inherited
+    /// variables. You can disable environment variable inheritance entirely using
+    /// [`Command::env_clear`] or for a single key using [`Command::env_remove`].
+    ///
+    /// Note that environment variable names are case-insensitive (but case-preserving) on Windows
+    /// and case-sensitive on all other platforms.
     ///
     /// # Examples
     ///
@@ -716,7 +737,18 @@ impl Command {
         self
     }
 
-    /// Removes an environment variable mapping.
+    /// Removes an explicitly set environment variable and prevents inheriting it from a parent
+    /// process.
+    ///
+    /// This method will remove the explicit value of an environment variable set via
+    /// [`Command::env`] or [`Command::envs`]. In addition, it will prevent the spawned child
+    /// process from inheriting that environment variable from its parent process.
+    ///
+    /// After calling [`Command::env_remove`], the value associated with its key from
+    /// [`Command::get_envs`] will be [`None`].
+    ///
+    /// To clear all explicitly set environment variables and disable all environment variable
+    /// inheritance, you can use [`Command::env_clear`].
     ///
     /// # Examples
     ///
@@ -736,7 +768,17 @@ impl Command {
         self
     }
 
-    /// Clears the entire environment map for the child process.
+    /// Clears all explicitly set environment variables and prevents inheriting any parent process
+    /// environment variables.
+    ///
+    /// This method will remove all explicitly added environment variables set via [`Command::env`]
+    /// or [`Command::envs`]. In addition, it will prevent the spawned child process from inheriting
+    /// any environment variable from its parent process.
+    ///
+    /// After calling [`Command::env_remove`], the iterator from [`Command::get_envs`] will be
+    /// empty.
+    ///
+    /// You can use [`Command::env_remove`] to clear a single mapping.
     ///
     /// # Examples
     ///
@@ -988,17 +1030,21 @@ impl Command {
         CommandArgs { inner: self.inner.get_args() }
     }
 
-    /// Returns an iterator of the environment variables that will be set when
-    /// the process is spawned.
+    /// Returns an iterator of the environment variables explicitly set for the child process.
+    ///
+    /// Environment variables explicitly set using [`Command::env`], [`Command::envs`], and
+    /// [`Command::env_remove`] can be retrieved with this method.
+    ///
+    /// Note that this output does not include environment variables inherited from the parent
+    /// process.
     ///
-    /// Each element is a tuple `(&OsStr, Option<&OsStr>)`, where the first
-    /// value is the key, and the second is the value, which is [`None`] if
-    /// the environment variable is to be explicitly removed.
+    /// Each element is a tuple key/value pair `(&OsStr, Option<&OsStr>)`. A [`None`] value
+    /// indicates its key was explicitly removed via [`Command::env_remove`]. The associated key for
+    /// the [`None`] value will no longer inherit from its parent process.
     ///
-    /// This only includes environment variables explicitly set with
-    /// [`Command::env`], [`Command::envs`], and [`Command::env_remove`]. It
-    /// does not include environment variables that will be inherited by the
-    /// child process.
+    /// An empty iterator can indicate that no explicit mappings were added or that
+    /// [`Command::env_clear`] was called. After calling [`Command::env_clear`], the child process
+    /// will not inherit any environment variables from its parent process.
     ///
     /// # Examples
     ///