Rollup merge of rust-lang#29708 - Ryman:pathdoc, r=steveklabnik

r? @steveklabnik

src/libstd/path.rs

@@ -1013,6 +1013,21 @@ impl PathBuf {
     /// * if `path` has a root but no prefix (e.g. `\windows`), it
     ///   replaces everything except for the prefix (if any) of `self`.
     /// * if `path` has a prefix but no root, it replaces `self`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::PathBuf;
+    ///
+    /// let mut path = PathBuf::new();
+    /// path.push("/tmp");
+    /// path.push("file.bk");
+    /// assert_eq!(path, PathBuf::from("/tmp/file.bk"));
+    ///
+    /// // Pushing an absolute path replaces the current path
+    /// path.push("/etc/passwd");
+    /// assert_eq!(path, PathBuf::from("/etc/passwd"));
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn push<P: AsRef<Path>>(&mut self, path: P) {
         self._push(path.as_ref())