Rollup merge of rust-lang#24342 - tbelaire:patch-1, r=huonw

It was mistakenly calling `with_extension` with "foo.txt" instead of "txt".
I've also added an assert.  This also calls more attention to the fact you get back a PathBuf, instead of a Path, which I feel is easy to miss when skimming.

Author: Manishearth

src/libstd/path.rs

@@ -1574,7 +1574,8 @@ impl Path {
     ///
     /// let path = Path::new("/tmp/foo.rs");
     ///
-    /// let new_path = path.with_extension("foo.txt");
+    /// let new_path = path.with_extension("txt");
+    /// assert_eq!(new_path, PathBuf::from("/tmp/foo.txt"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn with_extension<S: AsRef<OsStr>>(&self, extension: S) -> PathBuf {