Revise gix_path::env docstrings for clarity

gix-path/src/env/mod.rs

@@ -67,14 +67,16 @@ pub fn shell() -> &'static OsStr {
 }
 
 /// Return the name of the Git executable to invoke it.
+///
 /// If it's in the `PATH`, it will always be a short name.
 ///
 /// Note that on Windows, we will find the executable in the `PATH` if it exists there, or search it
 /// in alternative locations which when found yields the full path to it.
 pub fn exe_invocation() -> &'static Path {
     if cfg!(windows) {
-        /// The path to the Git executable as located in the `PATH` or in other locations that it's known to be installed to.
-        /// It's `None` if environment variables couldn't be read or if no executable could be found.
+        /// The path to the Git executable as located in the `PATH` or in other locations that it's
+        /// known to be installed to. It's `None` if environment variables couldn't be read or if
+        /// no executable could be found.
         static EXECUTABLE_PATH: Lazy<Option<PathBuf>> = Lazy::new(|| {
             std::env::split_paths(&std::env::var_os("PATH")?)
                 .chain(git::ALTERNATIVE_LOCATIONS.iter().map(Into::into))
@@ -99,11 +101,11 @@ pub fn exe_invocation() -> &'static Path {
     }
 }
 
-/// Returns the fully qualified path in the *xdg-home* directory (or equivalent in the home dir) to `file`,
-/// accessing `env_var(<name>)` to learn where these bases are.
+/// Returns the fully qualified path in the *xdg-home* directory (or equivalent in the home dir) to
+/// `file`, accessing `env_var(<name>)` to learn where these bases are.
 ///
-/// Note that the `HOME` directory should ultimately come from [`home_dir()`] as it handles windows correctly.
-/// The same can be achieved by using [`var()`] as `env_var`.
+/// Note that the `HOME` directory should ultimately come from [`home_dir()`] as it handles Windows
+/// correctly. The same can be achieved by using [`var()`] as `env_var`.
 pub fn xdg_config(file: &str, env_var: &mut dyn FnMut(&str) -> Option<OsString>) -> Option<PathBuf> {
     env_var("XDG_CONFIG_HOME")
         .map(|home| {
@@ -153,17 +155,17 @@ pub fn core_dir() -> Option<&'static Path> {
     GIT_CORE_DIR.as_deref()
 }
 
-/// Returns the platform dependent system prefix or `None` if it cannot be found (right now only on windows).
+/// Returns the platform dependent system prefix or `None` if it cannot be found (right now only on Windows).
 ///
 /// ### Performance
 ///
-/// On windows, the slowest part is the launch of the Git executable in the PATH, which only happens when launched
-/// from outside of the `msys2` shell.
+/// On Windows, the slowest part is the launch of the Git executable in the PATH. This is often
+/// avoided by inspecting the environment, when launched from inside a Git Bash MSYS2 shell.
 ///
 /// ### When `None` is returned
 ///
-/// This happens only windows if the git binary can't be found at all for obtaining its executable path, or if the git binary
-/// wasn't built with a well-known directory structure or environment.
+/// This happens only Windows if the git binary can't be found at all for obtaining its executable
+/// path, or if the git binary wasn't built with a well-known directory structure or environment.
 pub fn system_prefix() -> Option<&'static Path> {
     if cfg!(windows) {
         static PREFIX: Lazy<Option<PathBuf>> = Lazy::new(|| {
@@ -194,19 +196,20 @@ pub fn home_dir() -> Option<PathBuf> {
     std::env::var("HOME").map(PathBuf::from).ok()
 }
 
-/// Tries to obtain the home directory from `HOME` on all platforms, but falls back to [`home::home_dir()`] for
-/// more complex ways of obtaining a home directory, particularly useful on Windows.
+/// Tries to obtain the home directory from `HOME` on all platforms, but falls back to
+/// [`home::home_dir()`] for more complex ways of obtaining a home directory, particularly useful
+/// on Windows.
 ///
-/// The reason `HOME` is tried first is to allow Windows users to have a custom location for their linux-style
-/// home, as otherwise they would have to accumulate dot files in a directory these are inconvenient and perceived
-/// as clutter.
+/// The reason `HOME` is tried first is to allow Windows users to have a custom location for their
+/// linux-style home, as otherwise they would have to accumulate dot files in a directory these are
+/// inconvenient and perceived as clutter.
 #[cfg(not(target_family = "wasm"))]
 pub fn home_dir() -> Option<PathBuf> {
     std::env::var_os("HOME").map(Into::into).or_else(home::home_dir)
 }
 
-/// Returns the contents of an environment variable of `name` with some special handling
-/// for certain environment variables (like `HOME`) for platform compatibility.
+/// Returns the contents of an environment variable of `name` with some special handling for
+/// certain environment variables (like `HOME`) for platform compatibility.
 pub fn var(name: &str) -> Option<OsString> {
     if name == "HOME" {
         home_dir().map(PathBuf::into_os_string)