improve documentation, tests

Author: Qelxiros

library/std/src/fs.rs

@@ -1546,6 +1546,8 @@ impl crate::io::IoHandle for File {}
 impl Dir {
     /// Attempts to open a directory at `path` in read-only mode.
     ///
+    /// This function opens a directory. To open a file instead, see [`File::open`].
+    ///
     /// # Errors
     ///
     /// This function will return an error if `path` does not point to an existing directory.
@@ -1573,6 +1575,9 @@ impl Dir {
 
     /// Attempts to open a file in read-only mode relative to this directory.
     ///
+    /// This function interprets `path` relative to the directory provided by `self`. To open a file
+    /// relative to the current working directory, or at an absolute path, see [`File::open`].
+    ///
     /// # Errors
     ///
     /// This function will return an error if `path` does not point to an existing file.
@@ -1601,6 +1606,9 @@ impl Dir {
 
     /// Attempts to open a file according to `opts` relative to this directory.
     ///
+    /// This function interprets `path` relative to the directory provided by `self`. To open a file
+    /// relative to the current working directory, or at an absolute path, see [`File::open`].
+    ///
     /// # Errors
     ///
     /// This function will return an error if `path` does not point to an existing file.
@@ -1617,7 +1625,7 @@ impl Dir {
     ///     let mut opts = OpenOptions::new();
     ///     opts.read(true).write(true);
     ///     let mut f = dir.open_file_with("bar.txt", &opts)?;
-    ///     f.write(b"Hello, world!")?;
+    ///     f.write_all(b"Hello, world!")?;
     ///     let contents = io::read_to_string(f)?;
     ///     assert_eq!(contents, "Hello, world!");
     ///     Ok(())
@@ -1630,6 +1638,9 @@ impl Dir {
 
     /// Attempts to remove a file relative to this directory.
     ///
+    /// This function interprets `path` relative to the directory provided by `self`. To remove a file
+    /// relative to the current working directory, or at an absolute path, see [`fs::remove_file`][remove_file].
+    ///
     /// # Errors
     ///
     /// This function will return an error if `path` does not point to an existing file.
@@ -1655,6 +1666,9 @@ impl Dir {
     /// Attempts to rename a file or directory relative to this directory to a new name, replacing
     /// the destination file if present.
     ///
+    /// This function interprets `from` relative to the directory provided by `self` and `to` relative to the directory
+    /// provided by `to_dir`. To rename a file relative to the current working directory, or at an absolute path, see [`fs::rename`][rename].
+    ///
     /// # Errors
     ///
     /// This function will return an error if `from` does not point to an existing file or directory.

library/std/src/fs/tests.rs

@@ -2526,18 +2526,19 @@ fn test_fs_set_times_nofollow() {
 }
 
 #[test]
+#[cfg_attr(miri, ignore)] // FIXME: Miri does not support directory handles
 fn test_dir_smoke_test() {
     let tmpdir = tmpdir();
     let dir = Dir::open(tmpdir.path());
     check!(dir);
 }
 
 #[test]
+#[cfg_attr(miri, ignore)] // FIXME: Miri does not support directory handles
 fn test_dir_read_file() {
     let tmpdir = tmpdir();
     let mut f = check!(File::create(tmpdir.join("foo.txt")));
-    check!(f.write(b"bar"));
-    check!(f.flush());
+    check!(f.write_all(b"bar"));
     drop(f);
     let dir = check!(Dir::open(tmpdir.path()));
     let f = check!(dir.open_file("foo.txt"));
@@ -2549,8 +2550,7 @@ fn test_dir_read_file() {
 }
 
 #[test]
-// FIXME: libc calls fail on miri
-#[cfg(not(miri))]
+#[cfg_attr(miri, ignore)] // FIXME: Miri does not support directory handles
 fn test_dir_write_file() {
     let tmpdir = tmpdir();
     let dir = check!(Dir::open(tmpdir.path()));
@@ -2565,8 +2565,7 @@ fn test_dir_write_file() {
 }
 
 #[test]
-// FIXME: libc calls fail on miri
-#[cfg(not(miri))]
+#[cfg_attr(miri, ignore)] // FIXME: Miri does not support directory handles
 fn test_dir_remove_file() {
     let tmpdir = tmpdir();
     let mut f = check!(File::create(tmpdir.join("foo.txt")));
@@ -2579,13 +2578,11 @@ fn test_dir_remove_file() {
 }
 
 #[test]
-// FIXME: libc calls fail on miri
-#[cfg(not(miri))]
+#[cfg_attr(miri, ignore)] // FIXME: Miri does not support directory handles
 fn test_dir_rename_file() {
     let tmpdir = tmpdir();
     let mut f = check!(File::create(tmpdir.join("foo.txt")));
-    check!(f.write(b"bar"));
-    check!(f.flush());
+    check!(f.write_all(b"bar"));
     drop(f);
     let dir = check!(Dir::open(tmpdir.path()));
     check!(dir.rename("foo.txt", &dir, "baz.txt"));