Rollup merge of #126428 - kpreid:absolute, r=jhpratt

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

@@ -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

library/std/src/path.rs

@@ -3345,14 +3345,33 @@ fn description(&self) -> &str {
 /// 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
+/// All intermediate components will be resolved according to platform-specific
-/// rules but unlike [`canonicalize`][crate::fs::canonicalize] this does not
+/// 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
@@ -3375,10 +3394,6 @@ fn description(&self) -> &str {
 /// # 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
 ///
 /// ```
@@ -3400,10 +3415,6 @@ fn description(&self) -> &str {
 /// # 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