Skip to content

Commit

Permalink
Rollup merge of rust-lang#101648 - Timmmm:home_dir_docs, r=joshtriplett
Browse files Browse the repository at this point in the history
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: rust-lang#51656

See rust-lang#71684
  • Loading branch information
matthiaskrgr authored Dec 11, 2022
2 parents 657eefe + 8f0025e commit 668976b
Showing 1 changed file with 8 additions and 1 deletion.
9 changes: 8 additions & 1 deletion library/std/src/env.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 is not standard on Windows, and may not produce
/// desired results; for instance, under Cygwin or Mingw it will return `/home/you`
/// when it should return `C:\Users\you`.
///
/// # Examples
///
/// ```
Expand All @@ -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]
Expand Down

0 comments on commit 668976b

Please sign in to comment.