diff --git a/src/io/read/bytes.rs b/src/io/read/bytes.rs
index a45ee16..4224524 100644
--- a/src/io/read/bytes.rs
+++ b/src/io/read/bytes.rs
@@ -4,7 +4,7 @@ use crate::io::{self, Read};
 use crate::stream::stream::Stream;
 use crate::task::{Context, Poll};
 
-/// An iterator over `u8` values of a reader.
+/// A stream over `u8` values of a reader.
 ///
 /// This struct is generally created by calling [`bytes`] on a reader.
 /// Please see the documentation of [`bytes`] for more details.
diff --git a/src/io/read/chain.rs b/src/io/read/chain.rs
index e29b9bc..09517cc 100644
--- a/src/io/read/chain.rs
+++ b/src/io/read/chain.rs
@@ -23,18 +23,18 @@ impl<T, U> Chain<T, U> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let foo_file = File::open("foo.txt").await?;
-    ///     let bar_file = File::open("bar.txt").await?;
+    /// let foo_file = File::open("foo.txt").await?;
+    /// let bar_file = File::open("bar.txt").await?;
     ///
-    ///     let chain = foo_file.chain(bar_file);
-    ///     let (foo_file, bar_file) = chain.into_inner();
-    ///     Ok(())
-    /// }) }
+    /// let chain = foo_file.chain(bar_file);
+    /// let (foo_file, bar_file) = chain.into_inner();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn into_inner(self) -> (T, U) {
         (self.first, self.second)
@@ -45,18 +45,18 @@ impl<T, U> Chain<T, U> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let foo_file = File::open("foo.txt").await?;
-    ///     let bar_file = File::open("bar.txt").await?;
+    /// let foo_file = File::open("foo.txt").await?;
+    /// let bar_file = File::open("bar.txt").await?;
     ///
-    ///     let chain = foo_file.chain(bar_file);
-    ///     let (foo_file, bar_file) = chain.get_ref();
-    ///     Ok(())
-    /// }) }
+    /// let chain = foo_file.chain(bar_file);
+    /// let (foo_file, bar_file) = chain.get_ref();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn get_ref(&self) -> (&T, &U) {
         (&self.first, &self.second)
@@ -71,18 +71,18 @@ impl<T, U> Chain<T, U> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let foo_file = File::open("foo.txt").await?;
-    ///     let bar_file = File::open("bar.txt").await?;
+    /// let foo_file = File::open("foo.txt").await?;
+    /// let bar_file = File::open("bar.txt").await?;
     ///
-    ///     let mut chain = foo_file.chain(bar_file);
-    ///     let (foo_file, bar_file) = chain.get_mut();
-    ///     Ok(())
-    /// }) }
+    /// let mut chain = foo_file.chain(bar_file);
+    /// let (foo_file, bar_file) = chain.get_mut();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn get_mut(&mut self) -> (&mut T, &mut U) {
         (&mut self.first, &mut self.second)
diff --git a/src/io/read/mod.rs b/src/io/read/mod.rs
index 6b8ad71..9c81f95 100644
--- a/src/io/read/mod.rs
+++ b/src/io/read/mod.rs
@@ -282,21 +282,20 @@ extension_trait! {
             [`read()`]: tymethod.read
 
             ```no_run
+            # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+            #
             use async_std::io::prelude::*;
             use async_std::fs::File;
 
-            fn main() -> std::io::Result<()> {
-                async_std::task::block_on(async {
-                    let f = File::open("foo.txt").await?;
-                    let mut buffer = [0; 5];
+            let f = File::open("foo.txt").await?;
+            let mut buffer = [0; 5];
 
-                    // read at most five bytes
-                    let mut handle = f.take(5);
+            // read at most five bytes
+            let mut handle = f.take(5);
 
-                    handle.read(&mut buffer).await?;
-                    Ok(())
-                })
-            }
+            handle.read(&mut buffer).await?;
+            #
+            # Ok(()) }) }
             ```
         "#]
         fn take(self, limit: u64) -> take::Take<Self>
@@ -319,27 +318,27 @@ extension_trait! {
             [file]: ../fs/struct.File.html
            
             ```no_run
-            use async_std::io;
+            # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+            #
             use async_std::prelude::*;
             use async_std::fs::File;
            
-            fn main() -> io::Result<()> { async_std::task::block_on(async {
-                let mut f = File::open("foo.txt").await?;
-                let mut buffer = Vec::new();
-                let mut other_buffer = Vec::new();
+            let mut f = File::open("foo.txt").await?;
+            let mut buffer = Vec::new();
+            let mut other_buffer = Vec::new();
            
-                {
-                    let reference = f.by_ref();
+            {
+                let reference = f.by_ref();
            
-                    // read at most 5 bytes
-                    reference.take(5).read_to_end(&mut buffer).await?;
+                // read at most 5 bytes
+                reference.take(5).read_to_end(&mut buffer).await?;
            
-                } // drop our &mut reference so we can use f again
+            } // drop our &mut reference so we can use f again
            
-                // original file still usable, read the rest
-                f.read_to_end(&mut other_buffer).await?;
-                Ok(())
-            }) }
+            // original file still usable, read the rest
+            f.read_to_end(&mut other_buffer).await?;
+            #
+            # Ok(()) }) }
             ```
         "#]
         fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
@@ -360,19 +359,19 @@ extension_trait! {
             [file]: ../fs/struct.File.html
            
             ```no_run
-            use async_std::io;
+            # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+            #
             use async_std::prelude::*;
             use async_std::fs::File;
            
-            fn main() -> io::Result<()> { async_std::task::block_on(async {
-                let f = File::open("foo.txt").await?;
-                let mut s = f.bytes();
+            let f = File::open("foo.txt").await?;
+            let mut s = f.bytes();
            
-                while let Some(byte) = s.next().await {
-                    println!("{}", byte.unwrap());
-                }
-                Ok(())
-            }) }
+            while let Some(byte) = s.next().await {
+                println!("{}", byte.unwrap());
+            }
+            #
+            # Ok(()) }) }
             ```
         "#]
         fn bytes(self) -> bytes::Bytes<Self> where Self: Sized {
@@ -393,22 +392,22 @@ extension_trait! {
             [file]: ../fs/struct.File.html
            
             ```no_run
-            use async_std::io;
+            # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+            #
             use async_std::prelude::*;
             use async_std::fs::File;
            
-            fn main() -> io::Result<()> { async_std::task::block_on(async {
-                let f1 = File::open("foo.txt").await?;
-                let f2 = File::open("bar.txt").await?;
+            let f1 = File::open("foo.txt").await?;
+            let f2 = File::open("bar.txt").await?;
            
-                let mut handle = f1.chain(f2);
-                let mut buffer = String::new();
+            let mut handle = f1.chain(f2);
+            let mut buffer = String::new();
            
-                // read the value into a String. We could use any Read method here,
-                // this is just one example.
-                handle.read_to_string(&mut buffer).await?;
-                Ok(())
-            }) }
+            // read the value into a String. We could use any Read method here,
+            // this is just one example.
+            handle.read_to_string(&mut buffer).await?;
+            #
+            # Ok(()) }) }
             ```
         "#]
         fn chain<R: Read>(self, next: R) -> chain::Chain<Self, R> where Self: Sized {
diff --git a/src/io/read/take.rs b/src/io/read/take.rs
index b63f76d..def4e24 100644
--- a/src/io/read/take.rs
+++ b/src/io/read/take.rs
@@ -30,19 +30,19 @@ impl<T> Take<T> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let f = File::open("foo.txt").await?;
+    /// let f = File::open("foo.txt").await?;
     ///
-    ///     // read at most five bytes
-    ///     let handle = f.take(5);
+    /// // read at most five bytes
+    /// let handle = f.take(5);
     ///
-    ///     println!("limit: {}", handle.limit());
-    ///     Ok(())
-    /// }) }
+    /// println!("limit: {}", handle.limit());
+    /// #
+    /// #     Ok(()) }) }
     /// ```
     pub fn limit(&self) -> u64 {
         self.limit
@@ -56,20 +56,20 @@ impl<T> Take<T> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let f = File::open("foo.txt").await?;
+    /// let f = File::open("foo.txt").await?;
     ///
-    ///     // read at most five bytes
-    ///     let mut handle = f.take(5);
-    ///     handle.set_limit(10);
+    /// // read at most five bytes
+    /// let mut handle = f.take(5);
+    /// handle.set_limit(10);
     ///
-    ///     assert_eq!(handle.limit(), 10);
-    ///     Ok(())
-    /// }) }
+    /// assert_eq!(handle.limit(), 10);
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn set_limit(&mut self, limit: u64) {
         self.limit = limit;
@@ -80,20 +80,20 @@ impl<T> Take<T> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let file = File::open("foo.txt").await?;
+    /// let file = File::open("foo.txt").await?;
     ///
-    ///     let mut buffer = [0; 5];
-    ///     let mut handle = file.take(5);
-    ///     handle.read(&mut buffer).await?;
+    /// let mut buffer = [0; 5];
+    /// let mut handle = file.take(5);
+    /// handle.read(&mut buffer).await?;
     ///
-    ///     let file = handle.into_inner();
-    ///     Ok(())
-    /// }) }
+    /// let file = handle.into_inner();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn into_inner(self) -> T {
         self.inner
@@ -104,20 +104,20 @@ impl<T> Take<T> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let file = File::open("foo.txt").await?;
+    /// let file = File::open("foo.txt").await?;
     ///
-    ///     let mut buffer = [0; 5];
-    ///     let mut handle = file.take(5);
-    ///     handle.read(&mut buffer).await?;
+    /// let mut buffer = [0; 5];
+    /// let mut handle = file.take(5);
+    /// handle.read(&mut buffer).await?;
     ///
-    ///     let file = handle.get_ref();
-    ///     Ok(())
-    /// }) }
+    /// let file = handle.get_ref();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn get_ref(&self) -> &T {
         &self.inner
@@ -132,20 +132,20 @@ impl<T> Take<T> {
     /// # Examples
     ///
     /// ```no_run
-    /// use async_std::io;
+    /// # fn main() -> async_std::io::Result<()> { async_std::task::block_on(async {
+    /// #
     /// use async_std::prelude::*;
     /// use async_std::fs::File;
     ///
-    /// fn main() -> io::Result<()> { async_std::task::block_on(async {
-    ///     let file = File::open("foo.txt").await?;
+    /// let file = File::open("foo.txt").await?;
     ///
-    ///     let mut buffer = [0; 5];
-    ///     let mut handle = file.take(5);
-    ///     handle.read(&mut buffer).await?;
+    /// let mut buffer = [0; 5];
+    /// let mut handle = file.take(5);
+    /// handle.read(&mut buffer).await?;
     ///
-    ///     let file = handle.get_mut();
-    ///     Ok(())
-    /// }) }
+    /// let file = handle.get_mut();
+    /// #
+    /// # Ok(()) }) }
     /// ```
     pub fn get_mut(&mut self) -> &mut T {
         &mut self.inner