symlink: rename parameters and fix error messages to match std (#83)

Previously, upstream named the parameters to `fn symlink(src: P, dest: Q)`.
This is confusing because `dest` is the path of the link that's
_created_, not the _destination_ the link points to.

In fact, it's so confusing that all the error messages from this crate
listed the paths incorrectly: if
`fs_err::os::unix::fs::symlink("link-destination", "link-source")`
failed, the error message would say:

    failed to symlink file from link-destination to link-source

Now, in both `std` and `tokio`, these functions are named like `fn
symlink(original: P, link: Q)`. Let's update our wrappers to match the
new convention.

Author: 9999years

src/lib.rs

@@ -263,12 +263,17 @@ pub fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
 
 /// Creates a new hard link on the filesystem.
 ///
+/// The `link` path will be a link pointing to the `original` path. Note that
+/// systems often require these two paths to both be located on the same
+/// filesystem.
+///
 /// Wrapper for [`fs::hard_link`](https://doc.rust-lang.org/stable/std/fs/fn.hard_link.html).
-pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
-    let src = src.as_ref();
-    let dst = dst.as_ref();
-    fs::hard_link(src, dst)
-        .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::HardLink, src, dst))
+pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
+    let original = original.as_ref();
+    let link = link.as_ref();
+    fs::hard_link(original, link).map_err(|source| {
+        SourceDestError::build(source, SourceDestErrorKind::HardLink, link, original)
+    })
 }
 
 /// Reads a symbolic link, returning the file that the link points to.
@@ -289,15 +294,20 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
         .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::Rename, from, to))
 }
 
+/// Creates a new symbolic link on the filesystem.
+///
+/// The `link` path will be a symbolic link pointing to the `original` path.
+///
 /// Wrapper for [`fs::soft_link`](https://doc.rust-lang.org/stable/std/fs/fn.soft_link.html).
 #[deprecated = "replaced with std::os::unix::fs::symlink and \
 std::os::windows::fs::{symlink_file, symlink_dir}"]
-pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
-    let src = src.as_ref();
-    let dst = dst.as_ref();
+pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
+    let original = original.as_ref();
+    let link = link.as_ref();
     #[allow(deprecated)]
-    fs::soft_link(src, dst)
-        .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::SoftLink, src, dst))
+    fs::soft_link(original, link).map_err(|source| {
+        SourceDestError::build(source, SourceDestErrorKind::SoftLink, link, original)
+    })
 }
 
 /// Query the metadata about a file without following symlinks.

src/os/unix.rs

@@ -8,12 +8,15 @@ pub mod fs {
 
     /// Creates a new symbolic link on the filesystem.
     ///
+    /// The `link` path will be a symbolic link pointing to the `original` path.
+    ///
     /// Wrapper for [`std::os::unix::fs::symlink`](https://doc.rust-lang.org/std/os/unix/fs/fn.symlink.html)
-    pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
-        let src = src.as_ref();
-        let dst = dst.as_ref();
-        std::os::unix::fs::symlink(src, dst)
-            .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::Symlink, src, dst))
+    pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
+        let original = original.as_ref();
+        let link = link.as_ref();
+        std::os::unix::fs::symlink(original, link).map_err(|err| {
+            SourceDestError::build(err, SourceDestErrorKind::Symlink, link, original)
+        })
     }
 
     /// Wrapper for [`std::os::unix::fs::FileExt`](https://doc.rust-lang.org/std/os/unix/fs/trait.FileExt.html).

src/os/windows.rs

@@ -6,22 +6,28 @@ pub mod fs {
 
     /// Creates a new symlink to a directory on the filesystem.
     ///
+    /// The `link` path will be a symbolic link pointing to the `original` path.
+    ///
     /// Wrapper for [std::os::windows::fs::symlink_dir](https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html)
-    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
-        let src = src.as_ref();
-        let dst = dst.as_ref();
-        std::os::windows::fs::symlink_dir(src, dst)
-            .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkDir, src, dst))
+    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
+        let original = original.as_ref();
+        let link = link.as_ref();
+        std::os::windows::fs::symlink_dir(original, link).map_err(|err| {
+            SourceDestError::build(err, SourceDestErrorKind::SymlinkDir, link, original)
+        })
     }
 
     /// Creates a new symlink to a non-directory file on the filesystem.
     ///
+    /// The `link` path will be a symbolic link pointing to the `original` path.
+    ///
     /// Wrapper for [std::os::windows::fs::symlink_file](https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html)
-    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
-        let src = src.as_ref();
-        let dst = dst.as_ref();
-        std::os::windows::fs::symlink_file(src, dst)
-            .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkFile, src, dst))
+    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
+        let original = original.as_ref();
+        let link = link.as_ref();
+        std::os::windows::fs::symlink_file(original, link).map_err(|err| {
+            SourceDestError::build(err, SourceDestErrorKind::SymlinkFile, link, original)
+        })
     }
 
     /// Wrapper for [`std::os::windows::fs::FileExt`](https://doc.rust-lang.org/std/os/windows/fs/trait.FileExt.html).

src/tokio/mod.rs

@@ -64,13 +64,17 @@ pub async fn create_dir_all(path: impl AsRef<Path>) -> io::Result<()> {
 
 /// Creates a new hard link on the filesystem.
 ///
+/// The `link` path will be a link pointing to the `original` path. Note that
+/// systems often require these two paths to both be located on the same
+/// filesystem.
+///
 /// Wrapper for [`tokio::fs::hard_link`].
 #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
-pub async fn hard_link(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
-    let (src, dst) = (src.as_ref(), dst.as_ref());
-    tokio::fs::hard_link(src, dst)
+pub async fn hard_link(original: impl AsRef<Path>, link: impl AsRef<Path>) -> io::Result<()> {
+    let (original, link) = (original.as_ref(), link.as_ref());
+    tokio::fs::hard_link(original, link)
         .await
-        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::HardLink, src, dst))
+        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::HardLink, link, original))
 }
 
 /// Given a path, queries the file system to get information about a file,
@@ -199,38 +203,46 @@ pub async fn symlink_metadata(path: impl AsRef<Path>) -> io::Result<Metadata> {
 
 /// Creates a new symbolic link on the filesystem.
 ///
+/// The `link` path will be a symbolic link pointing to the `original` path.
+///
 /// Wrapper for [`tokio::fs::symlink`].
 #[cfg(unix)]
 #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
-pub async fn symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
-    let (src, dst) = (src.as_ref(), dst.as_ref());
-    tokio::fs::symlink(src, dst)
+pub async fn symlink(original: impl AsRef<Path>, link: impl AsRef<Path>) -> io::Result<()> {
+    let (original, link) = (original.as_ref(), link.as_ref());
+    tokio::fs::symlink(original, link)
         .await
-        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::Symlink, src, dst))
+        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::Symlink, link, original))
 }
 
 /// Creates a new directory symlink on the filesystem.
 ///
+/// The `link` path will be a symbolic link pointing to the `original` path.
+///
 /// Wrapper for [`tokio::fs::symlink_dir`].
 #[cfg(windows)]
 #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
-pub async fn symlink_dir(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
-    let (src, dst) = (src.as_ref(), dst.as_ref());
-    tokio::fs::symlink_dir(src, dst)
+pub async fn symlink_dir(original: impl AsRef<Path>, link: impl AsRef<Path>) -> io::Result<()> {
+    let (original, link) = (original.as_ref(), link.as_ref());
+    tokio::fs::symlink_dir(original, link)
         .await
-        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkDir, src, dst))
+        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkDir, link, original))
 }
 
 /// Creates a new file symbolic link on the filesystem.
 ///
+/// The `link` path will be a symbolic link pointing to the `original` path.
+///
 /// Wrapper for [`tokio::fs::symlink_file`].
 #[cfg(windows)]
 #[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
-pub async fn symlink_file(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
-    let (src, dst) = (src.as_ref(), dst.as_ref());
-    tokio::fs::symlink_file(src, dst)
+pub async fn symlink_file(original: impl AsRef<Path>, link: impl AsRef<Path>) -> io::Result<()> {
+    let (original, link) = (original.as_ref(), link.as_ref());
+    tokio::fs::symlink_file(original, link)
         .await
-        .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkFile, src, dst))
+        .map_err(|err| {
+            SourceDestError::build(err, SourceDestErrorKind::SymlinkFile, link, original)
+        })
 }
 
 /// Creates a future that will open a file for writing and write the entire