From c078c0ca2165643ea8e20132cf9ed5a772f8c54f Mon Sep 17 00:00:00 2001 From: Utkarsh Gupta Date: Thu, 27 Apr 2023 16:54:48 +0530 Subject: [PATCH 1/2] home: fix & enhance documentation --- crates/home/src/lib.rs | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/crates/home/src/lib.rs b/crates/home/src/lib.rs index a8af963f34e..b57f0bc2366 100644 --- a/crates/home/src/lib.rs +++ b/crates/home/src/lib.rs @@ -1,14 +1,5 @@ //! Canonical definitions of `home_dir`, `cargo_home`, and `rustup_home`. //! -//! This provides the definition of `home_dir` used by Cargo and -//! rustup, as well functions to find the correct value of -//! `CARGO_HOME` and `RUSTUP_HOME`. -//! -//! See also the [`dirs`](https://docs.rs/dirs) crate. -//! -//! _Note that as of 2019/08/06 it appears that cargo uses this crate. And -//! rustup has used this crate since 2019/08/21._ -//! //! The definition of `home_dir` provided by the standard library is //! incorrect because it considers the `HOME` environment variable on //! Windows. This causes surprising situations where a Rust program @@ -17,9 +8,11 @@ //! rustup use the standard libraries definition - they use the //! definition here. //! -//! This crate further provides two functions, `cargo_home` and +//! This crate provides two additional functions, `cargo_home` and //! `rustup_home`, which are the canonical way to determine the -//! location that Cargo and rustup store their data. +//! location that Cargo and rustup use to store their data. +//! The `env` module contains utilities for mocking the process environment +//! by Cargo and rustup. //! //! See also this [discussion]. //! @@ -36,29 +29,34 @@ mod windows; use std::io; use std::path::{Path, PathBuf}; -/// Returns the path of the current user's home directory if known. +/// Returns the path of the current user's home directory using environment +/// variables or OS-specific APIs. /// /// # Unix /// /// Returns the value of the `HOME` environment variable if it is set -/// and not equal to the empty string. Otherwise, it tries to determine the -/// home directory by invoking the `getpwuid_r` function on the UID of the -/// current user. +/// **even** if it is an empty string. Otherwise, it tries to determine the +/// home directory by invoking the [`getpwuid_r`][getpwuid] function with +/// the UID of the current user. +/// +/// [getpwuid]: https://linux.die.net/man/3/getpwuid_r /// /// # Windows /// -/// Returns the value of the `USERPROFILE` environment variable if it -/// is set and not equal to the empty string. If both do not exist, -/// [`SHGetFolderPathW`][msdn] is used to return the appropriate path. +/// Returns the value of the `USERPROFILE` environment variable if it is set +/// **and** it is not an empty string. Otherwise, it tries to determine the +/// home directory by invoking the [`SHGetFolderPathW`][shgfp] function with +/// [`CSIDL_PROFILE`][csidl]. /// -/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw +/// [shgfp]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw +/// [csidl]: https://learn.microsoft.com/en-us/windows/win32/shell/csidl /// /// # Examples /// /// ``` /// match home::home_dir() { -/// Some(path) => println!("{}", path.display()), -/// None => println!("Impossible to get your home dir!"), +/// Some(path) if !path.as_os_str().is_empty() => println!("{}", path.display()), +/// _ => println!("Unable to get your home dir!"), /// } /// ``` pub fn home_dir() -> Option { From fd1f1043e09e4bb77c808deb6244b5f8b9209f29 Mon Sep 17 00:00:00 2001 From: Utkarsh Gupta Date: Thu, 27 Apr 2023 22:00:19 +0530 Subject: [PATCH 2/2] home: bump version & update changelog --- Cargo.lock | 10 +++++----- crates/home/CHANGELOG.md | 4 ++++ crates/home/Cargo.toml | 2 +- crates/home/src/lib.rs | 2 +- 4 files changed, 11 insertions(+), 7 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 46188d1606c..ae98e6aaac1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -262,7 +262,7 @@ dependencies = [ "glob", "hex", "hmac", - "home 0.5.5 (registry+https://github.com/rust-lang/crates.io-index)", + "home 0.5.5", "http-auth", "humantime 2.1.0", "ignore", @@ -1546,7 +1546,7 @@ dependencies = [ "bstr", "gix-features", "gix-path", - "home 0.5.5 (registry+https://github.com/rust-lang/crates.io-index)", + "home 0.5.5", "thiserror", "url", ] @@ -1693,15 +1693,15 @@ dependencies = [ [[package]] name = "home" version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5444c27eef6923071f7ebcc33e3444508466a76f7a2b93da00ed6e19f30c1ddb" dependencies = [ "windows-sys 0.48.0", ] [[package]] name = "home" -version = "0.5.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5444c27eef6923071f7ebcc33e3444508466a76f7a2b93da00ed6e19f30c1ddb" +version = "0.5.6" dependencies = [ "windows-sys 0.48.0", ] diff --git a/crates/home/CHANGELOG.md b/crates/home/CHANGELOG.md index 425632ad5d5..58f960cc311 100644 --- a/crates/home/CHANGELOG.md +++ b/crates/home/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 0.5.6 +- Fixed & enhanced documentation. + [#12047](https://github.com/rust-lang/cargo/pull/12047) + ## 0.5.5 - 2023-04-25 - The `home` crate has migrated to the repository. [#11359](https://github.com/rust-lang/cargo/pull/11359) diff --git a/crates/home/Cargo.toml b/crates/home/Cargo.toml index 90211c28d78..3691d9c04a8 100644 --- a/crates/home/Cargo.toml +++ b/crates/home/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "home" -version = "0.5.5" # also update `html_root_url` in `src/lib.rs` +version = "0.5.6" # also update `html_root_url` in `src/lib.rs` authors = ["Brian Anderson "] documentation = "https://docs.rs/home" edition = "2018" diff --git a/crates/home/src/lib.rs b/crates/home/src/lib.rs index b57f0bc2366..0e1e975e476 100644 --- a/crates/home/src/lib.rs +++ b/crates/home/src/lib.rs @@ -18,7 +18,7 @@ //! //! [discussion]: https://github.com/rust-lang/rust/pull/46799#issuecomment-361156935 -#![doc(html_root_url = "https://docs.rs/home/0.5.5")] +#![doc(html_root_url = "https://docs.rs/home/0.5.6")] #![deny(rust_2018_idioms)] pub mod env;