From 416888f05b996f74eb696ed46c4eb3359a616f72 Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@switchb.org>
Date: Thu, 13 Jun 2024 11:59:22 -0700
Subject: [PATCH] Polish `std::path::absolute` documentation.
These changes bring it closer to other standard library documentation
and, in particular, `std::fs::canonicalize`, which it will often be
compared with.
* Add `# Platform-specific behavior` section, with content moved from
Examples section.
* Create `# Errors` section.
* Phrase error description to allow future platforms to have new
syntactic errors, rather than only emptiness.
* Add missing commas.
* Indent example code 4 spaces.
---
library/std/src/fs.rs | 2 +-
library/std/src/path.rs | 65 ++++++++++++++++++++++++-----------------
2 files changed, 39 insertions(+), 28 deletions(-)
diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 0dcf554770c5c..2132097fde459 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -2302,7 +2302,7 @@ pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
///
/// This function currently corresponds to the `realpath` function on Unix
/// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows.
-/// Note that, this [may change in the future][changes].
+/// Note that this [may change in the future][changes].
///
/// On Windows, this converts the path to use [extended length path][path]
/// syntax, which allows your program to use longer path names, but means you
diff --git a/library/std/src/path.rs b/library/std/src/path.rs
index adbcdcd2e67e3..7b8caaa268473 100644
--- a/library/std/src/path.rs
+++ b/library/std/src/path.rs
@@ -3345,14 +3345,33 @@ impl Error for StripPrefixError {
/// Makes the path absolute without accessing the filesystem.
///
/// If the path is relative, the current directory is used as the base directory.
-/// All intermediate components will be resolved according to platforms-specific
-/// rules but unlike [`canonicalize`][crate::fs::canonicalize] this does not
+/// All intermediate components will be resolved according to platform-specific
+/// rules, but unlike [`canonicalize`][crate::fs::canonicalize], this does not
/// resolve symlinks and may succeed even if the path does not exist.
///
/// If the `path` is empty or getting the
-/// [current directory][crate::env::current_dir] fails then an error will be
+/// [current directory][crate::env::current_dir] fails, then an error will be
/// returned.
///
+/// # Platform-specific behavior
+///
+/// On POSIX platforms, the path is resolved using [POSIX semantics][posix-semantics],
+/// except that it stops short of resolving symlinks. This means it will keep `..`
+/// components and trailing slashes.
+///
+/// On Windows, for verbatim paths, this will simply return the path as given. For other
+/// paths, this is currently equivalent to calling
+/// [`GetFullPathNameW`][windows-path].
+///
+/// Note that these [may change in the future][changes].
+///
+/// # Errors
+///
+/// This function may return an error in the following situations:
+///
+/// * If `path` is syntactically invalid; in particular, if it is empty.
+/// * If getting the [current directory][crate::env::current_dir] fails.
+///
/// # Examples
///
/// ## POSIX paths
@@ -3360,50 +3379,42 @@ impl Error for StripPrefixError {
/// ```
/// # #[cfg(unix)]
/// fn main() -> std::io::Result<()> {
-/// use std::path::{self, Path};
+/// use std::path::{self, Path};
///
-/// // Relative to absolute
-/// let absolute = path::absolute("foo/./bar")?;
-/// assert!(absolute.ends_with("foo/bar"));
+/// // Relative to absolute
+/// let absolute = path::absolute("foo/./bar")?;
+/// assert!(absolute.ends_with("foo/bar"));
///
-/// // Absolute to absolute
-/// let absolute = path::absolute("/foo//test/.././bar.rs")?;
-/// assert_eq!(absolute, Path::new("/foo/test/../bar.rs"));
-/// Ok(())
+/// // Absolute to absolute
+/// let absolute = path::absolute("/foo//test/.././bar.rs")?;
+/// assert_eq!(absolute, Path::new("/foo/test/../bar.rs"));
+/// Ok(())
/// }
/// # #[cfg(not(unix))]
/// # fn main() {}
/// ```
///
-/// The path is resolved using [POSIX semantics][posix-semantics] except that
-/// it stops short of resolving symlinks. This means it will keep `..`
-/// components and trailing slashes.
-///
/// ## Windows paths
///
/// ```
/// # #[cfg(windows)]
/// fn main() -> std::io::Result<()> {
-/// use std::path::{self, Path};
+/// use std::path::{self, Path};
///
-/// // Relative to absolute
-/// let absolute = path::absolute("foo/./bar")?;
-/// assert!(absolute.ends_with(r"foo\bar"));
+/// // Relative to absolute
+/// let absolute = path::absolute("foo/./bar")?;
+/// assert!(absolute.ends_with(r"foo\bar"));
///
-/// // Absolute to absolute
-/// let absolute = path::absolute(r"C:\foo//test\..\./bar.rs")?;
+/// // Absolute to absolute
+/// let absolute = path::absolute(r"C:\foo//test\..\./bar.rs")?;
///
-/// assert_eq!(absolute, Path::new(r"C:\foo\bar.rs"));
-/// Ok(())
+/// assert_eq!(absolute, Path::new(r"C:\foo\bar.rs"));
+/// Ok(())
/// }
/// # #[cfg(not(windows))]
/// # fn main() {}
/// ```
///
-/// For verbatim paths this will simply return the path as given. For other
-/// paths this is currently equivalent to calling
-/// [`GetFullPathNameW`][windows-path].
-///
/// Note that this [may change in the future][changes].
///
/// [changes]: io#platform-specific-behavior