diff --git a/tokio-fs/src/file/mod.rs b/tokio-fs/src/file/mod.rs
index c95f4f32f..d31c973be 100644
--- a/tokio-fs/src/file/mod.rs
+++ b/tokio-fs/src/file/mod.rs
@@ -34,6 +34,46 @@ use std::path::Path;
 /// Files are automatically closed when they go out of scope.
 ///
 /// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
+///
+/// # Examples
+///
+/// Create a new file and asynchronously write bytes to it:
+///
+/// ```no_run
+/// extern crate tokio;
+/// 
+/// use tokio::prelude::{AsyncWrite, Future};
+/// 
+/// fn main() {
+///     let task = tokio::fs::File::create("foo.txt")
+///         .and_then(|mut file| file.poll_write(b"hello, world!"))
+///         .map(|res| {
+///             println!("{:?}", res);
+///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+/// 
+///     tokio::run(task);
+/// }
+/// ```
+///
+/// Read the contents of a file into a buffer
+///
+/// ```no_run
+/// extern crate tokio;
+/// 
+/// use tokio::prelude::{AsyncRead, Future};
+/// 
+/// fn main() {
+///     let task = tokio::fs::File::open("foo.txt")
+///         .and_then(|mut file| {
+///             let mut contents = vec![];
+///             file.read_buf(&mut contents)
+///                 .map(|res| {
+///                     println!("{:?}", res);
+///                 })
+///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+///     tokio::run(task);
+/// }
+/// ```
 #[derive(Debug)]
 pub struct File {
     std: Option<StdFile>,
@@ -52,6 +92,23 @@ impl File {
     /// runtime or if the underlying [`open`] call results in an error.
     ///
     /// [`open`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.open
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// fn main() {
+    ///     let task = tokio::fs::File::open("foo.txt").and_then(|file| {
+    ///         // do something with the file ...
+    ///         file.metadata().map(|md| println!("{:?}", md))
+    ///     }).map_err(|e| {
+    ///         // handle errors
+    ///         eprintln!("IO error: {:?}", e);
+    ///     });
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn open<P>(path: P) -> OpenFuture<P>
     where P: AsRef<Path> + Send + 'static,
     {
@@ -73,15 +130,45 @@ impl File {
     /// runtime or if the underlying [`create`] call results in an error.
     ///
     /// [`create`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.create
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|file| {
+    ///             // do something with the created file ...
+    ///             file.metadata().map(|md| println!("{:?}", md))
+    ///         }).map_err(|e| {
+    ///             // handle errors
+    ///             eprintln!("IO error: {:?}", e);
+    ///     });
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn create<P>(path: P) -> CreateFuture<P>
     where P: AsRef<Path> + Send + 'static,
     {
         CreateFuture::new(path)
     }
 
-    /// Convert a [`std::fs::File`][std] to a `tokio_fs::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
+    ///
+    /// Examples
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use std::fs::File;
+    /// 
+    /// fn main() {
+    ///     let std_file = File::open("foo.txt").unwrap();
+    ///     let file = tokio::fs::File::from_std(std_file);
+    /// }
+    /// ```
     pub fn from_std(std: StdFile) -> File {
         File { std: Some(std) }
     }
@@ -98,6 +185,25 @@ impl File {
     /// # Errors
     ///
     /// Seeking to a negative offset is considered an error.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// use std::io::SeekFrom;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::open("foo.txt")
+    ///         // move cursor 6 bytes from the start of the file
+    ///         .and_then(|mut file| file.poll_seek(SeekFrom::Start(6)))
+    ///         .map(|res| {
+    ///             println!("{:?}", res);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_seek(&mut self, pos: io::SeekFrom) -> Poll<u64, io::Error> {
         ::blocking_io(|| self.std().seek(pos))
     }
@@ -108,6 +214,25 @@ impl File {
     ///
     /// This method consumes the `File` and returns it back when the future
     /// completes.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// use std::io::SeekFrom;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|file| file.seek(SeekFrom::Start(6)))
+    ///         .map(|file| {
+    ///             // handle returned file ..
+    ///             # println!("{:?}", file);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn seek(self, pos: io::SeekFrom) -> SeekFuture {
         SeekFuture::new(self, pos)
     }
@@ -116,6 +241,27 @@ impl File {
     ///
     /// This function will attempt to ensure that all in-core data reaches the
     /// filesystem before returning.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::{AsyncWrite, Future};
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|mut file| {
+    ///             file.poll_write(b"hello, world!")?;
+    ///             file.poll_sync_all()
+    ///         })
+    ///         .map(|res| {
+    ///             // handle returned result ..
+    ///             # println!("{:?}", res);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_sync_all(&mut self) -> Poll<(), io::Error> {
         ::blocking_io(|| self.std().sync_all())
     }
@@ -128,6 +274,27 @@ impl File {
     /// operations.
     ///
     /// Note that some platforms may simply implement this in terms of `poll_sync_all`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::{AsyncWrite, Future};
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|mut file| {
+    ///             file.poll_write(b"hello, world!")?;
+    ///             file.poll_sync_data()
+    ///         })
+    ///         .map(|res| {
+    ///             // handle returned result ..
+    ///             # println!("{:?}", res);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_sync_data(&mut self) -> Poll<(), io::Error> {
         ::blocking_io(|| self.std().sync_data())
     }
@@ -143,16 +310,71 @@ impl File {
     ///
     /// This function will return an error if the file is not opened for
     /// writing.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|mut file| {
+    ///             file.poll_set_len(10)
+    ///         })
+    ///         .map(|res| {
+    ///             // handle returned result ..
+    ///             # println!("{:?}", res);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_set_len(&mut self, size: u64) -> Poll<(), io::Error> {
         ::blocking_io(|| self.std().set_len(size))
     }
 
     /// Queries metadata about the underlying file.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|file| file.metadata())
+    ///         .map(|metadata| {
+    ///             println!("{:?}", metadata);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn metadata(self) -> MetadataFuture {
         MetadataFuture::new(self)
     }
 
     /// Queries metadata about the underlying file.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|mut file| file.poll_metadata())
+    ///         .map(|metadata| {
+    ///             // metadata is of type Async::Ready<Metadata>
+    ///             println!("{:?}", metadata);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_metadata(&mut self) -> Poll<Metadata, io::Error> {
         ::blocking_io(|| self.std().metadata())
     }
@@ -160,6 +382,24 @@ impl File {
     /// Create 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.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|mut file| file.poll_try_clone())
+    ///         .map(|clone| {
+    ///             // do something with the clone
+    ///             # println!("{:?}", clone);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_try_clone(&mut self) -> Poll<File, io::Error> {
         ::blocking_io(|| {
             let std = self.std().try_clone()?;
@@ -182,6 +422,28 @@ impl File {
     /// This function will return an error if the user lacks permission change
     /// attributes on the underlying file. It may also return an error in other
     /// os-specific unspecified cases.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .and_then(|file| file.metadata())
+    ///         .map(|(mut file, metadata)| {
+    ///             let mut perms = metadata.permissions();
+    ///             perms.set_readonly(true);
+    ///             match file.poll_set_permissions(perms) {
+    ///                 Err(e) => eprintln!("{}", e),
+    ///                 _ => println!("permissions set!"),
+    ///             }
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn poll_set_permissions(&mut self, perm: Permissions) -> Poll<(), io::Error> {
         ::blocking_io(|| self.std().set_permissions(perm))
     }
@@ -193,6 +455,24 @@ impl File {
     /// This function will panic if `shutdown` has been called.
     ///
     /// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # extern crate tokio;
+    /// use tokio::prelude::Future;
+    /// 
+    /// fn main() {
+    ///     let task = tokio::fs::File::create("foo.txt")
+    ///         .map(|file| {
+    ///             let std_file = file.into_std();
+    ///             // do something with the std::fs::File
+    ///             # println!("{:?}", std_file);
+    ///         }).map_err(|err| eprintln!("IO error: {:?}", err));
+    /// 
+    ///     tokio::run(task);
+    /// }
+    /// ```
     pub fn into_std(mut self) -> StdFile {
         self.std.take().expect("`File` instance already shutdown")
     }