1 files changed, 31 insertions, 8 deletions
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<Path>) -> io::Result<Vec<u8>> {
     let path = path.as_ref().to_owned();