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.

0 files changed, 0 insertions, 0 deletions