add documentation, implementations for unsupported platforms

Author: Qelxiros

library/std/src/fs.rs

@@ -133,8 +133,24 @@ pub enum TryLockError {
 }
 
 #[unstable(feature = "dirfd", issue = "120426")]
-#[cfg(target_family = "unix")]
 /// An object providing access to a directory on the filesystem.
+///
+/// Files are automatically closed when they go out of scope.  Errors detected
+/// on closing are ignored by the implementation of `Drop`.
+///
+/// # Examples
+///
+/// Opens a directory and then a file inside it.
+///
+/// ```no_run
+/// use std::fs::Dir;
+///
+/// fn main() -> std::io::Result<()> {
+///     let dir = Dir::new("/home/foo")?;
+///     let file = dir.open("bar.txt")?;
+///     Ok(())
+/// }
+/// ```
 pub struct Dir {
     inner: fs_imp::Dir,
 }
@@ -1460,13 +1476,21 @@ impl Seek for Arc<File> {
     }
 }
 
-#[unstable(feature = "dirfd", issue = "120426")]
 impl Dir {
     /// Opens a file relative to this directory.
+    ///
+    /// # Examples
+    /// ```no_run
+    /// use std::fs::Dir;
+    ///
+    /// let dir = Dir::new("foo")?;
+    /// ```
+    #[unstable(feature = "dirfd", issue = "120426")]
     pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
         self.inner.open(path).map(|f| File { inner: f })
     }
     /// Opens a file relative to this directory with the specified options.
+    #[unstable(feature = "dirfd", issue = "120426")]
     pub fn open_with<P: AsRef<Path>>(&self, path: P, opts: &OpenOptions) -> io::Result<File> {
         self.inner.open_with(path, &opts.0).map(|f| File { inner: f })
     }

library/std/src/sys/fs/unix.rs

@@ -300,12 +300,41 @@ impl Dir {
         })?;
         Ok(File(unsafe { FileDesc::from_raw_fd(fd) }))
     }
+}
 
-    // pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>
-    // pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(&self, from: P, to_dir: &Self, to: Q) -> Result<()>
-    // pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>
-    // pub fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>
-    // pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(&self, original: P, link: Q)
+#[cfg(any(
+    miri,
+    target_os = "redox",
+    target_os = "nto",
+    target_os = "vita",
+    target_os = "hurd",
+    target_os = "espidf",
+    target_os = "horizon",
+    target_os = "vxworks",
+    target_os = "rtems",
+    target_os = "nuttx",
+))]
+impl Dir {
+    pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
+        Err(io::const_error!(
+            io::ErrorKind::Unsupported,
+            "directory handles are not available for this platform",
+        ))
+    }
+
+    pub fn open_with<P: AsRef<Path>>(&self, path: P, opts: &OpenOptions) -> io::Result<File> {
+        Err(io::const_error!(
+            io::ErrorKind::Unsupported,
+            "directory handles are not available for this platform",
+        ))
+    }
+
+    pub fn open_c(&self, path: &CStr, opts: &OpenOptions) -> io::Result<File> {
+        Err(io::const_error!(
+            io::ErrorKind::Unsupported,
+            "directory handles are not available for this platform",
+        ))
+    }
 }
 
 fn get_path_from_fd(fd: c_int) -> Option<PathBuf> {