Add the initial paragraph of the original rustdoc to each wrapped fun…

…ction (#45)

src/dir.rs

@@ -5,6 +5,8 @@ use std::path::PathBuf;
 
 use crate::errors::{Error, ErrorKind};
 
+/// Returns an iterator over the entries within a directory.
+///
 /// Wrapper for [`fs::read_dir`](https://doc.rust-lang.org/stable/std/fs/fn.read_dir.html).
 pub fn read_dir<P: Into<PathBuf>>(path: P) -> io::Result<ReadDir> {
  let path = path.into();
@@ -51,25 +53,33 @@ pub struct DirEntry {
 }
 
 impl DirEntry {
+ /// Returns the full path to the file that this entry represents.
+ ///
  /// Wrapper for [`DirEntry::path`](https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html#method.path).
  pub fn path(&self) -> PathBuf {
  self.inner.path()
  }
 
+ /// Returns the metadata for the file that this entry points at.
+ ///
  /// Wrapper for [`DirEntry::metadata`](https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html#method.metadata).
  pub fn metadata(&self) -> io::Result<fs::Metadata> {
  self.inner
  .metadata()
  .map_err(|source| Error::build(source, ErrorKind::Metadata, self.path()))
  }
 
+ /// Returns the file type for the file that this entry points at.
+ ///
  /// Wrapper for [`DirEntry::file_type`](https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html#method.file_type).
  pub fn file_type(&self) -> io::Result<fs::FileType> {
  self.inner
  .file_type()
  .map_err(|source| Error::build(source, ErrorKind::Metadata, self.path()))
  }
 
+ /// Returns the file name of this directory entry without any leading path component(s).
+ ///
  /// Wrapper for [`DirEntry::file_name`](https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html#method.file_name).
  pub fn file_name(&self) -> OsString {
  self.inner.file_name()

src/file.rs

@@ -29,6 +29,8 @@ pub(crate) fn create(path: &Path) -> Result<std::fs::File, impl FnOnce(PathBuf)
 ///
 /// [std::fs::File]: https://doc.rust-lang.org/stable/std/fs/struct.File.html
 impl File {
+ /// Attempts to open a file in read-only mode.
+ ///
  /// Wrapper for [`File::open`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.open).
  pub fn open<P>(path: P) -> Result<Self, io::Error>
  where
@@ -41,6 +43,8 @@ impl File {
  }
  }
 
+ /// Opens a file in write-only mode.
+ ///
  /// Wrapper for [`File::create`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.create).
  pub fn create<P>(path: P) -> Result<Self, io::Error>
  where
@@ -69,34 +73,46 @@ impl File {
  }
  }
 
+ /// Attempts to sync all OS-internal metadata to disk.
+ ///
  /// Wrapper for [`File::sync_all`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.sync_all).
  pub fn sync_all(&self) -> Result<(), io::Error> {
  self.file
  .sync_all()
  .map_err(|source| self.error(source, ErrorKind::SyncFile))
  }
 
+ /// This function is similar to [`sync_all`], except that it might not synchronize file metadata to the filesystem.
+ ///
  /// Wrapper for [`File::sync_data`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.sync_data).
  pub fn sync_data(&self) -> Result<(), io::Error> {
  self.file
  .sync_data()
  .map_err(|source| self.error(source, ErrorKind::SyncFile))
  }
 
+ /// Truncates or extends the underlying file, updating the size of this file to become `size`.
+ ///
  /// Wrapper for [`File::set_len`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.set_len).
  pub fn set_len(&self, size: u64) -> Result<(), io::Error> {
  self.file
  .set_len(size)
  .map_err(|source| self.error(source, ErrorKind::SetLen))
  }
 
+ /// Queries metadata about the underlying file.
+ ///
  /// Wrapper for [`File::metadata`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.metadata).
  pub fn metadata(&self) -> Result<fs::Metadata, io::Error> {
  self.file
  .metadata()
  .map_err(|source| self.error(source, ErrorKind::Metadata))
  }
 
+ /// Creates a new `File` instance that shares the same underlying file handle as the
+ /// existing `File` instance. Reads, writes, and seeks will affect both `File`
+ /// instances simultaneously.
+ ///
  /// Wrapper for [`File::try_clone`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.try_clone).
  pub fn try_clone(&self) -> Result<Self, io::Error> {
  self.file
@@ -108,6 +124,8 @@ impl File {
  .map_err(|source| self.error(source, ErrorKind::Clone))
  }
 
+ /// Changes the permissions on the underlying file.
+ ///
  /// Wrapper for [`File::set_permissions`](https://doc.rust-lang.org/stable/std/fs/struct.File.html#method.set_permissions).
  pub fn set_permissions(&self, perm: fs::Permissions) -> Result<(), io::Error> {
  self.file

src/lib.rs

@@ -91,6 +91,8 @@ pub use file::*;
 pub use open_options::OpenOptions;
 pub use path::PathExt;
 
+/// Read the entire contents of a file into a bytes vector.
+///
 /// Wrapper for [`fs::read`](https://doc.rust-lang.org/stable/std/fs/fn.read.html).
 pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
  let path = path.as_ref();
@@ -101,6 +103,8 @@ pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
  Ok(bytes)
 }
 
+/// Read the entire contents of a file into a string.
+///
 /// Wrapper for [`fs::read_to_string`](https://doc.rust-lang.org/stable/std/fs/fn.read_to_string.html).
 pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {
  let path = path.as_ref();
@@ -111,6 +115,8 @@ pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {
  Ok(string)
 }
 
+/// Write a slice as the entire contents of a file.
+///
 /// Wrapper for [`fs::write`](https://doc.rust-lang.org/stable/std/fs/fn.write.html).
 pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result<()> {
  let path = path.as_ref();
@@ -120,6 +126,9 @@ pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result
  .map_err(|err| Error::build(err, ErrorKind::Write, path))
 }
 
+/// Copies the contents of one file to another. This function will also copy the
+/// permission bits of the original file to the destination file.
+///
 /// Wrapper for [`fs::copy`](https://doc.rust-lang.org/stable/std/fs/fn.copy.html).
 pub fn copy<P, Q>(from: P, to: Q) -> io::Result<u64>
 where
@@ -132,6 +141,8 @@ where
  .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::Copy, from, to))
 }
 
+/// Creates a new, empty directory at the provided path.
+///
 /// Wrapper for [`fs::create_dir`](https://doc.rust-lang.org/stable/std/fs/fn.create_dir.html).
 pub fn create_dir<P>(path: P) -> io::Result<()>
 where
@@ -141,6 +152,8 @@ where
  fs::create_dir(path).map_err(|source| Error::build(source, ErrorKind::CreateDir, path))
 }
 
+/// Recursively create a directory and all of its parent components if they are missing.
+///
 /// Wrapper for [`fs::create_dir_all`](https://doc.rust-lang.org/stable/std/fs/fn.create_dir_all.html).
 pub fn create_dir_all<P>(path: P) -> io::Result<()>
 where
@@ -150,6 +163,8 @@ where
  fs::create_dir_all(path).map_err(|source| Error::build(source, ErrorKind::CreateDir, path))
 }
 
+/// Removes an empty directory.
+///
 /// Wrapper for [`fs::remove_dir`](https://doc.rust-lang.org/stable/std/fs/fn.remove_dir.html).
 pub fn remove_dir<P>(path: P) -> io::Result<()>
 where
@@ -159,6 +174,8 @@ where
  fs::remove_dir(path).map_err(|source| Error::build(source, ErrorKind::RemoveDir, path))
 }
 
+/// Removes a directory at this path, after removing all its contents. Use carefully!
+///
 /// Wrapper for [`fs::remove_dir_all`](https://doc.rust-lang.org/stable/std/fs/fn.remove_dir_all.html).
 pub fn remove_dir_all<P>(path: P) -> io::Result<()>
 where
@@ -168,6 +185,8 @@ where
  fs::remove_dir_all(path).map_err(|source| Error::build(source, ErrorKind::RemoveDir, path))
 }
 
+/// Removes a file from the filesystem.
+///
 /// Wrapper for [`fs::remove_file`](https://doc.rust-lang.org/stable/std/fs/fn.remove_file.html).
 pub fn remove_file<P>(path: P) -> io::Result<()>
 where
@@ -177,18 +196,25 @@ where
  fs::remove_file(path).map_err(|source| Error::build(source, ErrorKind::RemoveFile, path))
 }
 
+/// Given a path, query the file system to get information about a file, directory, etc.
+///
 /// Wrapper for [`fs::metadata`](https://doc.rust-lang.org/stable/std/fs/fn.metadata.html).
 pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<fs::Metadata> {
  let path = path.as_ref();
  fs::metadata(path).map_err(|source| Error::build(source, ErrorKind::Metadata, path))
 }
 
+/// Returns the canonical, absolute form of a path with all intermediate components
+/// normalized and symbolic links resolved.
+///
 /// Wrapper for [`fs::canonicalize`](https://doc.rust-lang.org/stable/std/fs/fn.canonicalize.html).
 pub fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
  let path = path.as_ref();
  fs::canonicalize(path).map_err(|source| Error::build(source, ErrorKind::Canonicalize, path))
 }
 
+/// Creates a new hard link on the 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();
@@ -197,12 +223,16 @@ pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<(
  .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::HardLink, src, dst))
 }
 
+/// Reads a symbolic link, returning the file that the link points to.
+///
 /// Wrapper for [`fs::read_link`](https://doc.rust-lang.org/stable/std/fs/fn.read_link.html).
 pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
  let path = path.as_ref();
  fs::read_link(path).map_err(|source| Error::build(source, ErrorKind::ReadLink, path))
 }
 
+/// Rename a file or directory to a new name, replacing the original file if to already exists.
+///
 /// Wrapper for [`fs::rename`](https://doc.rust-lang.org/stable/std/fs/fn.rename.html).
 pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
  let from = from.as_ref();
@@ -222,13 +252,17 @@ pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<(
  .map_err(|source| SourceDestError::build(source, SourceDestErrorKind::SoftLink, src, dst))
 }
 
+/// Query the metadata about a file without following symlinks.
+///
 /// Wrapper for [`fs::symlink_metadata`](https://doc.rust-lang.org/stable/std/fs/fn.symlink_metadata.html).
 pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<fs::Metadata> {
  let path = path.as_ref();
  fs::symlink_metadata(path)
  .map_err(|source| Error::build(source, ErrorKind::SymlinkMetadata, path))
 }
 
+/// Changes the permissions found on a file or a directory.
+///
 /// Wrapper for [`fs::set_permissions`](https://doc.rust-lang.org/stable/std/fs/fn.set_permissions.html).
 pub fn set_permissions<P: AsRef<Path>>(path: P, perm: fs::Permissions) -> io::Result<()> {
  let path = path.as_ref();

src/open_options.rs

@@ -4,48 +4,64 @@ use std::{fs, io, path::PathBuf};
 pub struct OpenOptions(fs::OpenOptions);
 
 impl OpenOptions {
+ /// Creates a blank new set of options ready for configuration.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::new`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.new)
  #[allow(clippy::new_without_default)]
  pub fn new() -> Self {
  OpenOptions(fs::OpenOptions::new())
  }
 
+ /// Sets the option for read access.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::read`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.read)
  pub fn read(&mut self, read: bool) -> &mut Self {
  self.0.read(read);
  self
  }
 
+ /// Sets the option for write access.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::write`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.write)
  pub fn write(&mut self, write: bool) -> &mut Self {
  self.0.write(write);
  self
  }
 
+ /// Sets the option for the append mode.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::append`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.append)
  pub fn append(&mut self, append: bool) -> &mut Self {
  self.0.append(append);
  self
  }
 
+ /// Sets the option for truncating a previous file.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::truncate`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.truncate)
  pub fn truncate(&mut self, truncate: bool) -> &mut Self {
  self.0.truncate(truncate);
  self
  }
 
+ /// Sets the option to create a new file, or open it if it already exists.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::create`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create)
  pub fn create(&mut self, create: bool) -> &mut Self {
  self.0.create(create);
  self
  }
 
+ /// Sets the option to create a new file, failing if it already exists.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::create_new`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create_new)
  pub fn create_new(&mut self, create_new: bool) -> &mut Self {
  self.0.create_new(create_new);
  self
  }
 
+ /// Opens a file at `path` with the options specified by `self`.
+ ///
  /// Wrapper for [`std::fs::OpenOptions::open`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.open)
  pub fn open<P>(&self, path: P) -> io::Result<crate::File>
  where

src/os/unix.rs

@@ -6,6 +6,8 @@ pub mod fs {
  use crate::SourceDestError;
  use crate::SourceDestErrorKind;
 
+ /// Creates a new symbolic link on the filesystem.
+ ///
  /// 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();

src/os/windows.rs

@@ -3,6 +3,9 @@ pub mod fs {
  use crate::{SourceDestError, SourceDestErrorKind};
  use std::io;
  use std::path::Path;
+
+ /// Creates a new symlink to a directory on the filesystem.
+ ///
  /// 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();
@@ -11,6 +14,8 @@ pub mod fs {
  .map_err(|err| SourceDestError::build(err, SourceDestErrorKind::SymlinkDir, src, dst))
  }
 
+ /// Creates a new symlink to a non-directory file on the filesystem.
+ ///
  /// 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();

src/path.rs

@@ -10,17 +10,30 @@ use std::path::{Path, PathBuf};
 //
 // Because no one else can implement it, we can add methods backwards-compatibly.
 pub trait PathExt: crate::Sealed {
+ /// Returns Ok(true) if the path points at an existing entity.
+ ///
  /// Wrapper for [`Path::try_exists`](https://doc.rust-lang.org/std/path/struct.Path.html#method.try_exists).
  #[cfg(rustc_1_63)]
  fn fs_err_try_exists(&self) -> io::Result<bool>;
+ /// Given a path, query the file system to get information about a file, directory, etc.
+ ///
  /// Wrapper for [`crate::metadata`].
  fn fs_err_metadata(&self) -> io::Result<fs::Metadata>;
+ /// Query the metadata about a file without following symlinks.
+ ///
  /// Wrapper for [`crate::symlink_metadata`].
  fn fs_err_symlink_metadata(&self) -> io::Result<fs::Metadata>;
+ /// Returns the canonical, absolute form of a path with all intermediate components
+ /// normalized and symbolic links resolved.
+ ///
  /// Wrapper for [`crate::canonicalize`].
  fn fs_err_canonicalize(&self) -> io::Result<PathBuf>;
+ /// Reads a symbolic link, returning the file that the link points to.
+ ///
  /// Wrapper for [`crate::read_link`].
  fn fs_err_read_link(&self) -> io::Result<PathBuf>;
+ /// Returns an iterator over the entries within a directory.
+ ///
  /// Wrapper for [`crate::read_dir`].
  fn fs_err_read_dir(&self) -> io::Result<crate::ReadDir>;
 }