doc: fill out `fs` and remove html links (#2015)

also add an async version of `fs::canonicalize`

26 files changed, 605 insertions, 153 deletions

diff --git a/tokio/src/fs/canonicalize.rs b/tokio/src/fs/canonicalize.rs
new file mode 100644
index 00000000..40366268
--- /dev/null
+++ b/tokio/src/fs/canonicalize.rs
@@ -0,0 +1,51 @@
+use crate::fs::asyncify;
+
+use std::io;
+use std::path::{Path, PathBuf};
+
+/// Returns the canonical, absolute form of a path with all intermediate
+/// components normalized and symbolic links resolved.
+///
+/// This is an async version of [`std::fs::canonicalize`][std]
+///
+/// [std]: std::fs::canonicalize
+///
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `realpath` function on Unix
+/// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows.
+/// Note that, this [may change in the future][changes].
+///
+/// On Windows, this converts the path to use [extended length path][path]
+/// syntax, which allows your program to use longer path names, but means you
+/// can only join backslash-delimited paths to it, and it may be incompatible
+/// with other applications (if passed to the application on the command-line,
+/// or written to a file another application may read).
+///
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+/// [path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx#maxpath
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * `path` does not exist.
+/// * A non-final component in path is not a directory.
+///
+/// # Examples
+///
+/// ```no_run
+/// use tokio::fs;
+/// use std::io;
+///
+/// #[tokio::main]
+/// async fn main() -> io::Result<()> {
+///     let path = fs::canonicalize("../a/../foo.txt").await?;
+///     Ok(())
+/// }
+/// ```
+pub async fn canonicalize(path: impl AsRef<Path>) -> io::Result<PathBuf> {
+    let path = path.as_ref().to_owned();
+    asyncify(move || std::fs::canonicalize(path)).await
+}
diff --git a/tokio/src/fs/create_dir.rs b/tokio/src/fs/create_dir.rs
index 99762058..e03b04dc 100644
--- a/tokio/src/fs/create_dir.rs
+++ b/tokio/src/fs/create_dir.rs
@@ -7,7 +7,45 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::fs::create_dir`][std]
 ///
-/// [std]: https://doc.rust-lang.org/std/fs/fn.create_dir.html
+/// [std]: std::fs::create_dir
+///
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `mkdir` function on Unix
+/// and the `CreateDirectory` function on Windows.
+/// Note that, this [may change in the future][changes].
+///
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+///
+/// **NOTE**: If a parent of the given path doesn't exist, this function will
+/// return an error. To create a directory and all its missing parents at the
+/// same time, use the [`create_dir_all`] function.
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * User lacks permissions to create directory at `path`.
+/// * A parent of the given path doesn't exist. (To create a directory and all
+///   its missing parents at the same time, use the [`create_dir_all`]
+///   function.)
+/// * `path` already exists.
+///
+/// [`create_dir_all`]: super::create_dir_all()
+///
+/// # Examples
+///
+/// ```no_run
+/// use tokio::fs;
+/// use std::io;
+///
+/// #[tokio::main]
+/// async fn main() -> io::Result<()> {
+///     fs::create_dir("/some/dir").await?;
+///     Ok(())
+/// }
+/// ```
 pub async fn create_dir(path: impl AsRef<Path>) -> io::Result<()> {
     let path = path.as_ref().to_owned();
     asyncify(move || std::fs::create_dir(path)).await
diff --git a/tokio/src/fs/create_dir_all.rs b/tokio/src/fs/create_dir_all.rs
index 8c0c8df2..7d89280d 100644
--- a/tokio/src/fs/create_dir_all.rs
+++ b/tokio/src/fs/create_dir_all.rs
@@ -8,7 +8,45 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::fs::create_dir_all`][std]
 ///
-/// [std]: https://doc.rust-lang.org/std/fs/fn.create_dir_all.html
+/// [std]: std::fs::create_dir_all
+///
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `mkdir` function on Unix
+/// and the `CreateDirectory` function on Windows.
+/// Note that, this [may change in the future][changes].
+///
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * If any directory in the path specified by `path` does not already exist
+/// and it could not be created otherwise. The specific error conditions for
+/// when a directory is being created (after it is determined to not exist) are
+/// outlined by [`fs::create_dir`].
+///
+/// Notable exception is made for situations where any of the directories
+/// specified in the `path` could not be created as it was being created concurrently.
+/// Such cases are considered to be successful. That is, calling `create_dir_all`
+/// concurrently from multiple threads or processes is guaranteed not to fail
+/// due to a race condition with itself.
+///
+/// [`fs::create_dir`]: std::fs::create_dir
+///
+/// # Examples
+///
+/// ```no_run
+/// use tokio::fs;
+///
+/// #[tokio::main]
+/// async fn main() -> std::io::Result<()> {
+///     fs::create_dir_all("/some/dir").await?;
+///     Ok(())
+/// }
+/// ```
 pub async fn create_dir_all(path: impl AsRef<Path>) -> io::Result<()> {
     let path = path.as_ref().to_owned();
     asyncify(move || std::fs::create_dir_all(path)).await
diff --git a/tokio/src/fs/file.rs b/tokio/src/fs/file.rs
index a2f64e56..301d2380 100644
--- a/tokio/src/fs/file.rs
+++ b/tokio/src/fs/file.rs
@@ -1,6 +1,6 @@
 //! Types for working with [`File`].
 //!
-//! [`File`]: file/struct.File.html
+//! [`File`]: File
 
 use self::State::*;
 use crate::fs::{asyncify, sys};
@@ -29,7 +29,7 @@ use std::task::Poll::*;
 ///
 /// Files are automatically closed when they go out of scope.
 ///
-/// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
+/// [std]: std::fs::File
 ///
 /// # Examples
 ///
@@ -90,7 +90,7 @@ impl File {
     ///
     /// See [`OpenOptions`] for more details.
     ///
-    /// [`OpenOptions`]: struct.OpenOptions.html
+    /// [`OpenOptions`]: super::OpenOptions
     ///
     /// # Errors
     ///
@@ -128,14 +128,14 @@ impl File {
     ///
     /// See [`OpenOptions`] for more details.
     ///
-    /// [`OpenOptions`]: struct.OpenOptions.html
+    /// [`OpenOptions`]: super::OpenOptions
     ///
     /// # Errors
     ///
     /// Results in an error if called from outside of the Tokio runtime or if
     /// the underlying [`create`] call results in an error.
     ///
-    /// [`create`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.create
+    /// [`create`]: std::fs::File::create
     ///
     /// # Examples
     ///
@@ -155,10 +155,10 @@ impl File {
         Ok(File::from_std(std_file))
     }
 
-    /// Convert a [`std::fs::File`][std] to a [`tokio_fs::File`][file].
+    /// Convert a [`std::fs::File`][std] to a [`tokio::fs::File`][file].
     ///
-    /// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
-    /// [file]: struct.File.html
+    /// [std]: std::fs::File
+    /// [file]: File
     ///
     /// # Examples
     ///
@@ -399,6 +399,8 @@ impl File {
     ///
     /// Use `File::try_into_std` to attempt conversion immediately.
     ///
+    /// [std]: std::fs::File
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -417,6 +419,8 @@ impl File {
 
     /// Tries to immediately destructure `File` into a [`std::fs::File`][std].
     ///
+    /// [std]: std::fs::File
+    ///
     /// # Errors
     ///
     /// This function will return an error containing the file if some
diff --git a/tokio/src/fs/hard_link.rs b/tokio/src/fs/hard_link.rs
index e3a32afc..50cc17d2 100644
--- a/tokio/src/fs/hard_link.rs
+++ b/tokio/src/fs/hard_link.rs
@@ -5,12 +5,39 @@ use std::path::Path;
 
 /// Creates a new hard link on the filesystem.
 ///
+/// This is an async version of [`std::fs::hard_link`][std]
+///
+/// [std]: std::fs::hard_link
+///
 /// The `dst` path will be a link pointing to the `src` path. Note that systems
 /// often require these two paths to both be located on the same filesystem.
 ///
-/// This is an async version of [`std::fs::hard_link`][std]
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `link` function on Unix
+/// and the `CreateHardLink` function on Windows.
+/// Note that, this [may change in the future][changes].
+///
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The `src` path is not a file or doesn't exist.
+///
+/// # Examples
+///
+/// ```no_run
+/// use tokio::fs;
 ///
-/// [std]: https://doc.rust-lang.org/std/fs/fn.hard_link.html
+/// #[tokio::main]
+/// async fn main() -> std::io::Result<()> {
+///     fs::hard_link("a.txt", "b.txt").await?; // Hard link a.txt to b.txt
+///     Ok(())
+/// }
+/// ```
 pub async fn hard_link(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();
diff --git a/tokio/src/fs/metadata.rs b/tokio/src/fs/metadata.rs
index 3a830db3..6bbb44ad 100644
--- a/tokio/src/fs/metadata.rs
+++ b/tokio/src/fs/metadata.rs
@@ -4,7 +4,43 @@ use std::fs::Metadata;
 use std::io;
 use std::path::Path;
 
-/// Queries the file system metadata for a path.
+/// Given a path, query the file system to get information about a file,
+/// directory, etc.
+///
+/// This is an async version of [`std::fs::metadata`][std]
+///
+/// This function will traverse symbolic links to query information about the
+/// destination file.
+///
+/// # Platform-specific behavior
+///
+/// This function currently corresponds to the `stat` function on Unix and the
+/// `GetFileAttributesEx` function on Windows.  Note that, this [may change in
+/// the future][changes].
+///
+/// [std]: std::fs::metadata
+/// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior
+///
+/// # Errors
+///
+/// This function will return an error in the following situations, but is not
+/// limited to just these cases:
+///
+/// * The user lacks permissions to perform `metadata` call on `path`.
+/// * `path` does not exist.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use tokio::fs;
+///
+/// #[tokio::main]
+/// async fn main() -> std::io::Result<()> {
+///     let attr = fs::metadata("/some/file/path.txt").await?;
+///     // inspect attr ...
+///     Ok(())
+/// }
+/// ```
 pub async fn metadata(path: impl AsRef<Path>) -> io::Result<Metadata> {
     let path = path.as_ref().to_owned();
     asyncify(|| std::fs::metadata(path)).await
diff --git a/tokio/src/fs/mod.rs b/tokio/src/fs/mod.rs
index c462bf4b..266364b9 100644
--- a/tokio/src/fs/mod.rs
+++ b/tokio/src/fs/mod.rs
@@ -24,6 +24,9 @@
 //!
 //! [`AsyncRead`]: https://docs.rs/tokio-io/0.1/tokio_io/trait.AsyncRead.html
 
+mod canonicalize;
+pub use self::canonicalize::canonicalize;
+
 mod create_dir;
 pub use self::create_dir::create_dir;
 
diff --git a/tokio/src/fs/open_options.rs b/tokio/src/fs/open_options.rs
index 8931247f..3210f4b7 100644
--- a/tokio/src/fs/open_options.rs
+++ b/tokio/src/fs/open_options.rs
@@ -5,13 +5,69 @@ use std::path::Path;
 
 /// Options and flags which can be used to configure how a file is opened.
 ///
+/// This builder exposes the ability to configure how a [`File`] is opened and
+/// what operations are permitted on the open file. The [`File::open`] and
+/// [`File::create`] methods are aliases for commonly used options using this
+/// builder.
+///
+/// Generally speaking, when using `OpenOptions`, you'll first call [`new`],
+/// then chain calls to methods to set each option, then call [`open`], passing
+/// the path of the file you're trying to open. This will give you a
+/// [`io::Result`][result] with a [`File`] inside that you can further operate
+/// on.
+///
 /// This is a specialized version of [`std::fs::OpenOptions`] for usage from
 /// the Tokio runtime.
 ///
 /// `From<std::fs::OpenOptions>` is implemented for more advanced configuration
 /// than the methods provided here.
 ///
-/// [`std::fs::OpenOptions`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html
+/// [`new`]: OpenOptions::new
+/// [`open`]: OpenOptions::open
+/// [result]: std::io::Result
+/// [`File`]: File
+/// [`File::open`]: File::open
+/// [`File::create`]: File::create
+/// [`std::fs::OpenOptions`]: std::fs::OpenOptions
+///
+/// # Examples
+///
+/// Opening a file to read:
+///
+/// ```no_run
+/// use tokio::fs::OpenOptions;
+/// use std::io;
+///
+/// #[tokio::main]
+/// async fn main() -> io::Result<()> {
+///     let file = OpenOptions::new()
+///         .read(true)
+///         .open("foo.txt")
+///         .await?;
+///
+///     Ok(())
+/// }
+/// ```
+///
+/// Opening a file for both reading and writing, as well as creating it if it
+/// doesn't exist:
+///
+/// ```no_run
+/// use tokio::fs::OpenOptions;
+/// use std::io;
+///
+/// #[tokio::main]
+/// async fn main() -> io::Result<()> {
+///     let file = OpenOptions::new()
+///         .read(true)
+///         .write(true)
+///         .create(true)
+///         .open("foo.txt")
+///         .await?;
+///
+///     Ok(())
+/// }
+/// ```
 #[derive(Clone, Debug)]
 pub struct OpenOptions(std::fs::OpenOptions);
 
@@ -20,9 +76,13 @@ impl OpenOptions {
     ///
     /// All options are initially set to `false`.
     ///
+    /// This is an async version of [`std::fs::OpenOptions::new`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::new
+    ///
     /// # Examples
     ///
-    /// ```ignore
+    /// ```no_run
     /// use tokio::fs::OpenOptions;
     ///
     /// let mut options = OpenOptions::new();
@@ -32,49 +92,232 @@ impl OpenOptions {
         OpenOptions(std::fs::OpenOptions::new())
     }
 
-    /// See the underlying [`read`] call for details.
+    /// Sets the option for read access.
+    ///
+    /// This option, when true, will indicate that the file should be
+    /// `read`-able if opened.
     ///
-    /// [`read`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.read
+    /// This is an async version of [`std::fs::OpenOptions::read`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::read
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .read(true)
+    ///         .open("foo.txt")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn read(&mut self, read: bool) -> &mut OpenOptions {
         self.0.read(read);
         self
     }
 
-    /// See the underlying [`write`] call for details.
+    /// Sets the option for write access.
     ///
-    /// [`write`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.write
+    /// This option, when true, will indicate that the file should be
+    /// `write`-able if opened.
+    ///
+    /// This is an async version of [`std::fs::OpenOptions::write`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::write
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .write(true)
+    ///         .open("foo.txt")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn write(&mut self, write: bool) -> &mut OpenOptions {
         self.0.write(write);
         self
     }
 
-    /// See the underlying [`append`] call for details.
+    /// Sets the option for the append mode.
+    ///
+    /// This option, when true, means that writes will append to a file instead
+    /// of overwriting previous contents.  Note that setting
+    /// `.write(true).append(true)` has the same effect as setting only
+    /// `.append(true)`.
+    ///
+    /// For most filesystems, the operating system guarantees that all writes are
+    /// atomic: no writes get mangled because another process writes at the same
+    /// time.
+    ///
+    /// One maybe obvious note when using append-mode: make sure that all data
+    /// that belongs together is written to the file in one operation. This
+    /// can be done by concatenating strings before passing them to [`write()`],
+    /// or using a buffered writer (with a buffer of adequate size),
+    /// and calling [`flush()`] when the message is complete.
+    ///
+    /// If a file is opened with both read and append access, beware that after
+    /// opening, and after every write, the position for reading may be set at the
+    /// end of the file. So, before writing, save the current position (using
+    /// [`seek`]`(`[`SeekFrom`]`::`[`Current`]`(0))`), and restore it before the next read.
+    ///
+    /// This is an async version of [`std::fs::OpenOptions::append`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::append
+    ///
+    /// ## Note
+    ///
+    /// This function doesn't create the file if it doesn't exist. Use the [`create`]
+    /// method to do so.
+    ///
+    /// [`write()`]: crate::io::AsyncWriteExt::write
+    /// [`flush()`]: crate::io::AsyncWriteExt::flush
+    /// [`seek`]: crate::io::AsyncSeekExt::seek
+    /// [`SeekFrom`]: std::io::SeekFrom
+    /// [`Current`]: std::io::SeekFrom::Current
+    /// [`create`]: OpenOptions::create
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
     ///
-    /// [`append`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.append
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .append(true)
+    ///         .open("foo.txt")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn append(&mut self, append: bool) -> &mut OpenOptions {
         self.0.append(append);
         self
     }
 
-    /// See the underlying [`truncate`] call for details.
+    /// Sets the option for truncating a previous file.
+    ///
+    /// If a file is successfully opened with this option set it will truncate
+    /// the file to 0 length if it already exists.
+    ///
+    /// The file must be opened with write access for truncate to work.
+    ///
+    /// This is an async version of [`std::fs::OpenOptions::truncate`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::truncate
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .write(true)
+    ///         .truncate(true)
+    ///         .open("foo.txt")
+    ///         .await?;
     ///
-    /// [`truncate`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.truncate
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn truncate(&mut self, truncate: bool) -> &mut OpenOptions {
         self.0.truncate(truncate);
         self
     }
 
-    /// See the underlying [`create`] call for details.
+    /// Sets the option for creating a new file.
+    ///
+    /// This option indicates whether a new file will be created if the file
+    /// does not yet already exist.
+    ///
+    /// In order for the file to be created, [`write`] or [`append`] access must
+    /// be used.
     ///
-    /// [`create`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create
+    /// This is an async version of [`std::fs::OpenOptions::create`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::create
+    /// [`write`]: OpenOptions::write
+    /// [`append`]: OpenOptions::append
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .write(true)
+    ///         .create(true)
+    ///         .open("foo.txt")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn create(&mut self, create: bool) -> &mut OpenOptions {
         self.0.create(create);
         self
     }
 
-    /// See the underlying [`create_new`] call for details.
+    /// Sets the option to always create a new file.
     ///
-    /// [`create_new`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create_new
+    /// This option indicates whether a new file will be created.  No file is
+    /// allowed to exist at the target location, also no (dangling) symlink.
+    ///
+    /// This option is useful because it is atomic. Otherwise between checking
+    /// whether a file exists and creating a new one, the file may have been
+    /// created by another process (a TOCTOU race condition / attack).
+    ///
+    /// If `.create_new(true)` is set, [`.create()`] and [`.truncate()`] are
+    /// ignored.
+    ///
+    /// The file must be opened with write or append access in order to create a
+    /// new file.
+    ///
+    /// This is an async version of [`std::fs::OpenOptions::create_new`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::create_new
+    /// [`.create()`]: OpenOptions::create
+    /// [`.truncate()`]: OpenOptions::truncate
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new()
+    ///         .write(true)
+    ///         .create_new(true)
+    ///         .open("foo.txt")
+    ///         .await?;
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn create_new(&mut self, create_new: bool) -> &mut OpenOptions {
         self.0.create_new(create_new);
         self
@@ -82,12 +325,56 @@ impl OpenOptions {
 
     /// Opens a file at `path` with the options specified by `self`.
     ///
+    /// This is an async version of [`std::fs::OpenOptions::open`][std]
+    ///
+    /// [std]: std::fs::OpenOptions::open
+    ///
     /// # Errors
     ///
-    /// `OpenOptionsFuture` results in an error if called from outside of the
-    /// Tokio runtime or if the underlying [`open`] call results in an error.
+    /// This function will return an error under a number of different
+    /// circumstances. Some of these error conditions are listed here, together
+    /// with their [`ErrorKind`]. The mapping to [`ErrorKind`]s is not part of
+    /// the compatibility contract of the function, especially the `Other` kind
+    /// might change to more specific kinds in the future.
+    ///
+    /// * [`NotFound`]: The specified file does not exist and neither `create`
+    ///   or `create_new` is set.
+    /// * [`NotFound`]: One of the directory components of the file path does
+    ///   not exist.
+    /// * [`PermissionDenied`]: The user lacks permission to get the specified
+    ///   access rights for the file.
+    /// * [`PermissionDenied`]: The user lacks permission to open one of the
+    ///   directory components of the specified path.
+    /// * [`AlreadyExists`]: `create_new` was specified and the file already
+    ///   exists.
+    /// * [`InvalidInput`]: Invalid combinations of open options (truncate
+    ///   without write access, no access mode set, etc.).
+    /// * [`Other`]: One of the directory components of the specified file path
+    ///   was not, in fact, a directory.
+    /// * [`Other`]: Filesystem-level errors: full disk, write permission
+    ///   requested on a read-only file system, exceeded disk quota, too many
+    ///   open files, too long filename, too many symbolic links in the
+    ///   specified path (Unix-like systems only), etc.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use tokio::fs::OpenOptions;
+    /// use std::io;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let file = OpenOptions::new().open("foo.txt").await?;
+    ///     Ok(())
+    /// }
+    /// ```
     ///
-    /// [`open`]: https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.open
+    /// [`ErrorKind`]: std::io::ErrorKind
+    /// [`AlreadyExists`]: std::io::ErrorKind::AlreadyExists
+    /// [`InvalidInput`]: std::io::ErrorKind::InvalidInput
+    /// [`NotFound`]: std::io::ErrorKind::NotFound
+    /// [`Other`]: std::io::ErrorKind::Other
+    /// [`PermissionDenied`]: std::io::ErrorKind::PermissionDenied
     pub async fn open(&self, path: impl AsRef<Path>) -> io::Result<File> {
         let path = path.as_ref().to_owned();
         let opts = self.0.clone();
diff --git a/tokio/src/fs/os/unix/symlink.rs b/tokio/src/fs/os/unix/symlink.rs
index 3d539446..22ece725 100644
--- a/tokio/src/fs/os/unix/symlink.rs
+++ b/tokio/src/fs/os/unix/symlink.rs
@@ -9,7 +9,7 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::os::unix::fs::symlink`][std]
 ///
-/// [std]: https://doc.rust-lang.org/std/os/unix/fs/fn.symlink.html
+/// [std]: std::os::unix::fs::symlink
 pub async fn symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();
diff --git a/tokio/src/fs/os/windows/symlink_dir.rs b/tokio/src/fs/os/windows/symlink_dir.rs
index 6753c25e..736e762b 100644
--- a/tokio/src/fs/os/windows/symlink_dir.rs
+++ b/tokio/src/fs/os/windows/symlink_dir.rs
@@ -10,7 +10,7 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::os::windows::fs::symlink_dir`][std]
 ///
-/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html
+/// [std]: std::os::windows::fs::symlink_dir
 pub async fn symlink_dir(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();
diff --git a/tokio/src/fs/os/windows/symlink_file.rs b/tokio/src/fs/os/windows/symlink_file.rs
index 623352a1..07d8e604 100644
--- a/tokio/src/fs/os/windows/symlink_file.rs
+++ b/tokio/src/fs/os/windows/symlink_file.rs
@@ -10,7 +10,7 @@ use std::path::Path;
 ///
 /// This is an async version of [`std::os::windows::fs::symlink_file`][std]
 ///
-/// [std]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html
+/// [std]: std::os::windows::fs::symlink_file
 pub async fn symlink_file(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> io::Result<()> {
     let src = src.as_ref().to_owned();
     let dst = dst.as_ref().to_owned();
diff --git a/tokio/src/fs/read.rs b/tokio/src/fs/read.rs
index 796acbf8..f61275d0 100644
--- a/tokio/src/fs/read.rs
+++ b/tokio/src/fs/read.rs
@@ -2,21 +2,44 @@ use crate::fs::asyncify;
 
 use std::{io, path::Path};
 
-/// Creates a future which will open a file for reading and read the entire
-/// contents into a buffer and return said buffer.
+/// Read the entire contents of a file into a bytes vector.
 ///
-/// This is the async equivalent of `std::fs::read`.
+/// This is an async version of [`std::fs::read`][std]
+///
+/// [std]: std::fs::read
+///
+/// This is a convenience function for using [`File::open`] and [`read_to_end`]
+/// with fewer imports and without an intermediate variable. It pre-allocates a
+/// buffer based on the file size when available, so it is generally faster than
+/// reading into a vector created with `Vec::new()`.
+///
+/// [`File::open`]: super::File::open
+/// [`read_to_end`]: crate::io::AsyncReadExt::read_to_end
+///
+/// # Errors
+///
+/// This function will return an error if `path` does not already exist.
+/// Other errors may also be returned according to [`OpenOptions::open`].
+///
+/// [`OpenOptions::open`]: super::OpenOptions::open
+///
+/// It will also return an error if it encounters while reading an error
+/// of a kind other than [`ErrorKind::Interrupted`].
+///
+/// [`ErrorKind::Interrupted`]: std::io::ErrorKind::Interrupted
 ///
 /// # Examples
 ///
 /// ```no_run
 /// use tokio::fs;
+/// use std::net::SocketAddr;
 ///
-/// # async fn dox() -> std::io::Result<()> {
-/// let contents = fs::read("foo.txt").await?;
-/// println!("foo.txt contains {} bytes", contents.len());
-/// # Ok(())
-/// # }
+/// #[tokio::main]
+/// async fn main() -> Result<(), Box<dyn std::error::Error + 'static>> {
+///     let contents = fs::read("address.txt").await?;
+///     let foo: SocketAddr = String::from_utf8_lossy(&contents).parse()?;
+///     Ok(())
+/// }
 /// ```
 pub async fn read(path: impl AsRef<Pa