Rollup merge of rust-lang#107114 - Erk-:add-absolute-note-to-path-joi…

…n, r=m-ou-se

Add note about absolute paths to Path::join

The note already exists on `PathBuf::push`, but I think it is good to have it on `Path::join` as well since it can cause issues if you are not careful with your input.

library/std/src/path.rs

@@ -2531,6 +2531,8 @@ impl Path {
 
     /// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
     ///
+    /// If `path` is absolute, it replaces the current path.
+    ///
     /// See [`PathBuf::push`] for more details on what it means to adjoin a path.
     ///
     /// # Examples
@@ -2539,6 +2541,7 @@ impl Path {
     /// use std::path::{Path, PathBuf};
     ///
     /// assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd"));
+    /// assert_eq!(Path::new("/etc").join("/bin/sh"), PathBuf::from("/bin/sh"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[must_use]