diff options
| author | Tim Hutt <tdhutt@gmail.com> | 2022-09-10 12:43:30 +0100 |
|---|---|---|
| committer | Tim Hutt <tdhutt@gmail.com> | 2022-09-10 12:43:30 +0100 |
| commit | 8d08983c2b14e5277580015006e334104cbbd7d1 (patch) | |
| tree | 84d1553a4fcde670b8131008790a11b48f83c712 | |
| parent | db9d86b58dff2a19d84d5e557641dfbb4cbb3a8d (diff) | |
| download | rust-8d08983c2b14e5277580015006e334104cbbd7d1.tar.gz rust-8d08983c2b14e5277580015006e334104cbbd7d1.zip | |
Better documentation for env::home_dir()'s broken behaviour
This improves the documentation to say *why* it was deprecated. The reason was because it reads `HOME` on Windows which is meaningless there. Note that the PR that deprecated it stated that returning an empty string if `HOME` is set to an empty string was a problem, however I can find no evidence that this is the case. `cd` handles it fine whereas if `HOME` is unset it gives an explicit `HOME not set` error. * Original deprecation reason: https://internals.rust-lang.org/t/deprecate-or-break-fix-std-env-home-dir/7315 * Original deprecation PR: https://github.com/rust-lang/rust/pull/51656 See #71684
| -rw-r--r-- | library/std/src/env.rs | 9 |
1 files changed, 8 insertions, 1 deletions
diff --git a/library/std/src/env.rs b/library/std/src/env.rs index 463f714064c..d78b1d7c9cf 100644 --- a/library/std/src/env.rs +++ b/library/std/src/env.rs @@ -570,6 +570,13 @@ impl Error for JoinPathsError { /// /// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya /// +/// # Deprecation +/// +/// This function is deprecated because the behaviour on Windows is not correct. +/// The 'HOME' environment variable has no meaning on Windows so it should not +/// be checked. This result is that under Cygwin or Mingw it will return `/home/you` +/// when it should return `C:\Users\you`. +/// /// # Examples /// /// ``` @@ -582,7 +589,7 @@ impl Error for JoinPathsError { /// ``` #[deprecated( since = "1.29.0", - note = "This function's behavior is unexpected and probably not what you want. \ + note = "This function's behavior may be unexpected on Windows. \ Consider using a crate from crates.io instead." )] #[must_use] |