Expand PathBuf documentation to show some strange behaviour

Author: ChrisJefferson

library/std/src/path.rs

@@ -1156,6 +1156,20 @@ impl FusedIterator for Ancestors<'_> {}
 /// ```
 ///
 /// Which method works best depends on what kind of situation you're in.
+///
+/// Note that `PathBuf`` does not sanitize arguments, and will build
+/// paths from strings which include separators, for example:
+///
+/// use std::path::PathBuf;
+///
+/// let mut path = PathBuf::new();
+///
+/// path.push(r"C:\");
+/// path.push("windows");
+/// path.push(r"..\otherdir");
+/// path.push("system32");
+///
+/// path.set_extension(r"\..\temp");
 #[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct PathBuf {
@@ -1379,6 +1393,8 @@ impl PathBuf {
     /// `file_name`. The new path will be a sibling of the original path.
     /// (That is, it will have the same parent.)
     ///
+    /// The argument is not sanitized, so can include separators.
+    ///
     /// [`self.file_name`]: Path::file_name
     /// [`pop`]: PathBuf::pop
     ///
@@ -1399,6 +1415,12 @@ impl PathBuf {
     ///
     /// buf.set_file_name("baz");
     /// assert!(buf == PathBuf::from("/baz"));
+    ///
+    /// buf.set_file_name("../b/c.txt");
+    /// assert!(buf == PathBuf::from("/../b/c.txt"));
+    ///
+    /// buf.set_file_name("baz");
+    /// assert!(buf == PathBuf::from("/../b/baz"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn set_file_name<S: AsRef<OsStr>>(&mut self, file_name: S) {
@@ -1434,6 +1456,8 @@ impl PathBuf {
     /// If the file stem contains internal dots and `extension` is empty, part
     /// of the old file stem will be considered the new [`self.extension`].
     ///
+    /// The new `extension` is not sanitized, so may include separators.
+    ///
     /// See the examples below.
     ///
     /// [`self.file_name`]: Path::file_name
@@ -1463,6 +1487,9 @@ impl PathBuf {
     ///
     /// p.set_extension("");
     /// assert_eq!(Path::new("/feel/the"), p.as_path());
+    ///
+    /// p.set_extension("/darkest.cookie");
+    /// assert_eq!(Path::new("/feel/the./darkest.cookie"), p.as_path());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool {