auto merge of #16443 : steveklabnik/rust/fix_path_docs, r=kballard

Originally discovered here: http://www.reddit.com/r/rust/comments/2dbg3j/hm_unwrap_is_being_renamed_to_assert/cjnxiax

src/libstd/path/windows.rs

@@ -628,18 +628,36 @@ impl GenericPath for Path {
 }
 
 impl Path {
-    /// Returns a new Path from a byte vector or string
+    /// Returns a new `Path` from a `BytesContainer`.
     ///
     /// # Failure
     ///
-    /// Fails the task if the vector contains a NUL.
-    /// Fails if invalid UTF-8.
+    /// Fails if the vector contains a `NUL`, or if it contains invalid UTF-8.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// println!("{}", Path::new(r"C:\some\path").display());
+    /// ```
     #[inline]
     pub fn new<T: BytesContainer>(path: T) -> Path {
         GenericPath::new(path)
     }
 
-    /// Returns a new Path from a byte vector or string, if possible
+    /// Returns a new `Some(Path)` from a `BytesContainer`.
+    ///
+    /// Returns `None` if the vector contains a `NUL`, or if it contains invalid UTF-8.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// let path = Path::new_opt(r"C:\some\path");
+    ///
+    /// match path {
+    ///     Some(path) => println!("{}", path.display()),
+    ///     None       => println!("There was a problem with your path."),
+    /// }
+    /// ```
     #[inline]
     pub fn new_opt<T: BytesContainer>(path: T) -> Option<Path> {
         GenericPath::new_opt(path)