Clarify that std::fs::rename can move

Fixes rust-lang#24816

Author: steveklabnik

src/libstd/fs.rs

@@ -844,6 +844,9 @@ pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
 
 /// Rename a file or directory to a new name.
 ///
+/// Moving a file or directory is also a rename, in a sense, and so this
+/// function is not limited a single directory.
+///
 /// # Errors
 ///
 /// This function will return an error if the provided `from` doesn't exist, if
@@ -861,6 +864,17 @@ pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
 /// # Ok(())
 /// # }
 /// ```
+///
+/// Moving:
+///
+/// ```
+/// use std::fs;
+///
+/// # fn foo() -> std::io::Result<()> {
+/// try!(fs::rename("from/a.txt", "to/b.txt"));
+/// # Ok(())
+/// # }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
     fs_imp::rename(from.as_ref(), to.as_ref())