Add documentation about symlink's argument order. (#232)

The order of the arguments to the `symlink` function could reasonably go
either of two different ways. And it appears cap-std picked one way and
the openat crate [picked the other way]. Both ways have a reason why they
make sense, and both ways also have the potential for user surprise.

cap-std's overarching reason for its choice is to follow std as closely
as possible. std's `symlink`, following POSIX `symlink` and `ln -s`,
puts the link name second. So a user converting `std` code to `cap-std`
code would just need to add a `Dir` as the `self` argument, without
needing to reorder anything. I think that still makes sense, but I'm
open to feedback here.

One thing that makes sense no matter which way is chosen is to document it,
so this patch adds documentation comments. And, it renames the arguments
from `src` and `dst` to `original` and `link` to match the naming used in
the `symlink` function in std.

[picked the other way]: https://docs.rs/openat/0.1.21/openat/struct.Dir.html#method.symlink

Author: sunfishcode

cap-async-std/src/fs/dir.rs

@@ -535,28 +535,52 @@ impl Dir {
 
     /// Creates a new symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::unix::fs::symlink`], but only
     /// accesses paths relative to `self`.
     ///
     /// [`async_std::os::unix::fs::symlink`]: https://docs.rs/async-std/latest/async_std/os/unix/fs/fn.symlink.html
     #[cfg(not(windows))]
     #[inline]
-    pub async fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(&self, src: P, dst: Q) -> io::Result<()> {
-        let src = src.as_ref().to_path_buf();
-        let dst = dst.as_ref().to_path_buf();
+    pub async fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(
+        &self,
+        original: P,
+        link: Q,
+    ) -> io::Result<()> {
+        let original = original.as_ref().to_path_buf();
+        let link = link.as_ref().to_path_buf();
         let clone = self.clone();
         spawn_blocking(move || {
             symlink(
-                src.as_ref(),
+                original.as_ref(),
                 &clone.as_filelike_view::<std::fs::File>(),
-                dst.as_ref(),
+                link.as_ref(),
             )
         })
         .await
     }
 
     /// Creates a new file symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::windows::fs::symlink_file`], but
     /// only accesses paths relative to `self`.
     ///
@@ -565,24 +589,34 @@ impl Dir {
     #[inline]
     pub async fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(
         &self,
-        src: P,
-        dst: Q,
+        original: P,
+        link: Q,
     ) -> io::Result<()> {
-        let src = src.as_ref().to_path_buf();
-        let dst = dst.as_ref().to_path_buf();
+        let original = original.as_ref().to_path_buf();
+        let link = link.as_ref().to_path_buf();
         let clone = self.clone();
         spawn_blocking(move || {
             symlink_file(
-                src.as_ref(),
+                original.as_ref(),
                 &clone.as_filelike_view::<std::fs::File>(),
-                dst.as_ref(),
+                link.as_ref(),
             )
         })
         .await
     }
 
     /// Creates a new directory symlink on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::windows::fs::symlink_dir`], but
     /// only accesses paths relative to `self`.
     ///
@@ -591,17 +625,17 @@ impl Dir {
     #[inline]
     pub async fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(
         &self,
-        src: P,
-        dst: Q,
+        original: P,
+        link: Q,
     ) -> io::Result<()> {
-        let src = src.as_ref().to_path_buf();
-        let dst = dst.as_ref().to_path_buf();
+        let original = original.as_ref().to_path_buf();
+        let link = link.as_ref().to_path_buf();
         let clone = self.clone();
         spawn_blocking(move || {
             symlink_dir(
-                src.as_ref(),
+                original.as_ref(),
                 &clone.as_filelike_view::<std::fs::File>(),
-                dst.as_ref(),
+                link.as_ref(),
             )
         })
         .await

cap-async-std/src/fs_utf8/dir.rs

@@ -354,6 +354,16 @@ impl Dir {
 
     /// Creates a new symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::unix::fs::symlink`], but only
     /// accesses paths relative to `self`.
     ///
@@ -362,16 +372,26 @@ impl Dir {
     #[inline]
     pub async fn symlink<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
         &self,
-        src: P,
-        dst: Q,
+        original: P,
+        link: Q,
     ) -> io::Result<()> {
-        let src = from_utf8(src)?;
-        let dst = from_utf8(dst)?;
-        self.cap_std.symlink(src, dst).await
+        let original = from_utf8(original)?;
+        let link = from_utf8(link)?;
+        self.cap_std.symlink(original, link).await
     }
 
     /// Creates a new file symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::windows::fs::symlink_file`], but
     /// only accesses paths relative to `self`.
     ///
@@ -380,16 +400,26 @@ impl Dir {
     #[inline]
     pub async fn symlink_file<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
         &self,
-        src: P,
-        dst: Q,
+        original: P,
+        link: Q,
     ) -> io::Result<()> {
-        let src = from_utf8(src)?;
-        let dst = from_utf8(dst)?;
-        self.cap_std.symlink_file(src, dst).await
+        let original = from_utf8(original)?;
+        let link = from_utf8(link)?;
+        self.cap_std.symlink_file(original, link).await
     }
 
     /// Creates a new directory symlink on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`async_std::os::windows::fs::symlink_dir`], but
     /// only accesses paths relative to `self`.
     ///
@@ -398,12 +428,12 @@ impl Dir {
     #[inline]
     pub async fn symlink_dir<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
         &self,
-        src: P,
-        dst: Q,
+        original: P,
+        link: Q,
     ) -> io::Result<()> {
-        let src = from_utf8(src)?;
-        let dst = from_utf8(dst)?;
-        self.cap_std.symlink_dir(src, dst).await
+        let original = from_utf8(original)?;
+        let link = from_utf8(link)?;
+        self.cap_std.symlink_dir(original, link).await
     }
 
     /// Creates a new `UnixListener` bound to the specified socket.

cap-std/src/fs/dir.rs

@@ -395,38 +395,76 @@ impl Dir {
 
     /// Creates a new symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`std::os::unix::fs::symlink`], but only accesses
     /// paths relative to `self`.
     ///
     /// [`std::os::unix::fs::symlink`]: https://doc.rust-lang.org/std/os/unix/fs/fn.symlink.html
     #[cfg(not(windows))]
     #[inline]
-    pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(&self, src: P, dst: Q) -> io::Result<()> {
-        symlink(src.as_ref(), &self.std_file, dst.as_ref())
+    pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(&self, original: P, link: Q) -> io::Result<()> {
+        symlink(original.as_ref(), &self.std_file, link.as_ref())
     }
 
     /// Creates a new file symbolic link on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`std::os::windows::fs::symlink_file`], but only
     /// accesses paths relative to `self`.
     ///
     /// [`std::os::windows::fs::symlink_file`]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html
     #[cfg(windows)]
     #[inline]
-    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(&self, src: P, dst: Q) -> io::Result<()> {
-        symlink_file(src.as_ref(), &self.std_file, dst.as_ref())
+    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(
+        &self,
+        original: P,
+        link: Q,
+    ) -> io::Result<()> {
+        symlink_file(original.as_ref(), &self.std_file, link.as_ref())
     }
 
     /// Creates a new directory symlink on a filesystem.
     ///
+    /// The `original` argument provides the target of the symlink. The `link`
+    /// argument provides the name of the created symlink.
+    ///
+    /// Despite the argument ordering, `original` is not resolved relative to
+    /// `self` here. `link` is resolved relative to `self`, and `original` is
+    /// not resolved within this function.
+    ///
+    /// The `link` path is resolved when the symlink is dereferenced, relative
+    /// to the directory that contains it.
+    ///
     /// This corresponds to [`std::os::windows::fs::symlink_dir`], but only
     /// accesses paths relative to `self`.
     ///
     /// [`std::os::windows::fs::symlink_dir`]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html
     #[cfg(windows)]
     #[inline]
-    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(&self, src: P, dst: Q) -> io::Result<()> {
-        symlink_dir(src.as_ref(), &self.std_file, dst.as_ref())
+    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(
+        &self,
+        original: P,
+        link: Q,
+    ) -> io::Result<()> {
+        symlink_dir(original.as_ref(), &self.std_file, link.as_ref())
     }
 
     /// Creates a new `UnixListener` bound to the specified socket.