diff --git a/src/lib.rs b/src/lib.rs
index 27bab602f..30da51b8b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -117,6 +117,7 @@
 //! ``` ignore
 //! //! An implementation of the `embedded-hal` for STM32F103xx microcontrollers
 //!
+//! extern crate core;
 //! extern crate embedded_hal as hal;
 //! extern crate nb;
 //!
@@ -130,40 +131,50 @@
 //! // and USART3
 //! pub struct Serial<'a, U>(pub &'a U)
 //! where
-//!     U: Deref<stm32f103xx::usart1::RegisterBlock> + 'static;
+//!     U: Deref<Target=stm32f103xx::usart1::RegisterBlock> + 'static;
 //!
 //! /// Serial interface error
 //! pub enum Error {
 //!     /// Buffer overrun
 //!     Overrun,
-//!     ..
+//!     // add more error variants here
 //! }
 //!
-//! impl<'a, U> hal::Serial for Serial<'a, U> {
+//! impl<'a, U> hal::serial::Read<u8> for Serial<'a, U>
+//!     where
+//!         U: Deref<Target=stm32f103xx::usart1::RegisterBlock> + 'static
+//! {
 //!     type Error = Error;
 //!
 //!     fn read(&self) -> nb::Result<u8, Error> {
 //!         // read the status register
-//!         let sr = self.sr.read();
+//!         let sr = self.0.sr.read();
 //!
-//!         if sr.ovr().bit_is_set() {
+//!         if sr.ore().bit_is_set() {
 //!             // Error: Buffer overrun
 //!             Err(nb::Error::Other(Error::Overrun))
-//!         } else if .. {
-//!             // Other error conditions
-//!             ..
-//!         } else if sr.rxne().bit_is_set() {
+//!         }
+//!         // Add additional `else if` statements to check for other errors
+//!         else if sr.rxne().bit_is_set() {
 //!             // Data available: read the data register
-//!             Ok(self.dr.read())
-//!         } else {
+//!             Ok(self.0.dr.read().bits() as u8)
+//!         }
+//!         else {
 //!             // No data available yet
 //!             Err(nb::Error::WouldBlock)
 //!         }
 //!     }
+//! }
+//!
+//! impl<'a, U> hal::serial::Write<u8> for Serial<'a, U>
+//!     where
+//!         U: Deref<Target=stm32f103xx::usart1::RegisterBlock> + 'static
+//! {
+//!     type Error = Error;
 //!
 //!     fn write(&self, byte: u8) -> nb::Result<(), Error> {
 //!         // Very similar to the above implementation
-//!         ..
+//!         Ok(())
 //!     }
 //! }
 //! ```
@@ -179,6 +190,9 @@
 //! implementation:
 //!
 //! ``` ignore
+//! extern crate embedded_hal as hal;
+//! extern crate nb;
+//!
 //! /// A synchronized serial interface
 //! // NOTE This is a global singleton
 //! pub struct Serial1;
@@ -186,9 +200,11 @@
 //! // NOTE private
 //! static USART1: Mutex<_> = Mutex::new(..);
 //!
-//! impl hal::Serial for Serial {
-//!     fn read(&self) -> Result<u8, nb::Error<Error>> {
-//!         hal::Serial::read(&Serial(USART1.lock()))
+//! impl hal::serial::Read<u8> for Serial1 {
+//!     type Error = !;
+//!
+//!     fn read(&self) -> Result<u8, nb::Error<Self::Error>> {
+//!         hal::serial::Read::read(&Serial(&*USART1.lock()))
 //!     }
 //! }
 //! ```
@@ -242,41 +258,58 @@
 //! extern crate nb;
 //!
 //! use hal::prelude::*;
+//! use futures::{
+//!     future,
+//!     Async,
+//!     Future,
+//! };
+//! use futures::future::Loop;
 //! use stm32f103xx_hal_impl::{Serial, Timer};
 //!
 //! /// `futures` version of `Timer.wait`
 //! ///
 //! /// This returns a future that must be polled to completion
-//! fn wait<T>(timer: &T) -> impl Future<Item = (), Error = !>
+//! fn wait<T>(timer: T) -> impl Future<Item = T, Error = !>
 //! where
 //!     T: hal::Timer,
 //! {
-//!     future::poll_fn(|| {
-//!         Ok(Async::Ready(try_nb!(timer.wait())))
+//!     future::loop_fn(timer, |timer| {
+//!         match timer.wait() {
+//!             Ok(())                     => Ok(Loop::Break(timer)),
+//!             Err(nb::Error::WouldBlock) => Ok(Loop::Continue(timer)),
+//!         }
 //!     })
 //! }
 //!
 //! /// `futures` version of `Serial.read`
 //! ///
 //! /// This returns a future that must be polled to completion
-//! fn read<S>(serial: &S) -> impl Future<Item = u8, Error = Error>
+//! fn read<S>(serial: S) -> impl Future<Item = (S, u8), Error = S::Error>
 //! where
-//!     S: hal::Serial,
+//!     S: hal::serial::Read<u8>,
 //! {
-//!     future::poll_fn(|| {
-//!         Ok(Async::Ready(try_nb!(serial.read())))
+//!     future::loop_fn(serial, |mut serial| {
+//!         match serial.read() {
+//!             Ok(byte)                     => Ok(Loop::Break((serial, byte))),
+//!             Err(nb::Error::WouldBlock)   => Ok(Loop::Continue(serial)),
+//!             Err(nb::Error::Other(error)) => Err(error),
+//!         }
 //!     })
 //! }
 //!
 //! /// `futures` version of `Serial.write`
 //! ///
 //! /// This returns a future that must be polled to completion
-//! fn write<S>(byte: u8) -> impl Future<Item = (), Error = Error>
+//! fn write<S>(serial: S, byte: u8) -> impl Future<Item = S, Error = S::Error>
 //! where
-//!     S: hal::Serial,
+//!     S: hal::serial::Write<u8>,
 //! {
-//!     future::poll_fn(|| {
-//!         Ok(Async::Ready(try_nb!(serial.write(byte))))
+//!     future::loop_fn(serial, move |mut serial| {
+//!         match serial.write(byte) {
+//!             Ok(())                       => Ok(Loop::Break(serial)),
+//!             Err(nb::Error::WouldBlock)   => Ok(Loop::Continue(serial)),
+//!             Err(nb::Error::Other(error)) => Err(error),
+//!         }
 //!     })
 //! }
 //!
@@ -285,7 +318,7 @@
 //! let serial = Serial(usart1);
 //!
 //! // Tasks
-//! let mut blinky = future::loop_fn(true, |_| {
+//! let mut blinky = future::loop_fn(true, |state| {
 //!     wait(timer).map(|_| {
 //!         if state {
 //!             Led.on();
@@ -381,14 +414,16 @@
 //!
 //! ``` ignore
 //! extern crate embedded_hal as hal;
+//! #[macro_use]
+//! extern crate nb;
 //!
 //! use hal::prelude::*;
 //!
 //! fn write_all<S>(serial: &S, buffer: &[u8]) -> Result<(), S::Error>
 //! where
-//!     S: hal::Serial
+//!     S: hal::serial::Write<u8>
 //! {
-//!     for byte in buffer {
+//!     for &byte in buffer {
 //!         block!(serial.write(byte))?;
 //!     }
 //!
@@ -400,23 +435,24 @@
 //!
 //! ``` ignore
 //! extern crate embedded_hal as hal;
+//! extern crate nb;
 //!
 //! use hal::prelude::*;
 //!
 //! enum Error<E> {
 //!     /// Serial interface error
-//!     Serial(E)
+//!     Serial(E),
 //!     TimedOut,
 //! }
 //!
-//! fn read_with_timeout(
+//! fn read_with_timeout<S, T>(
 //!     serial: &S,
 //!     timer: &T,
-//!     timeout: T::Ticks,
+//!     timeout: T::Time,
 //! ) -> Result<u8, Error<S::Error>>
 //! where
 //!     T: hal::Timer,
-//!     S: hal::Serial,
+//!     S: hal::serial::Read<u8>,
 //! {
 //!     timer.pause();
 //!     timer.restart();
@@ -433,6 +469,12 @@
 //!         }
 //!
 //!         match timer.wait() {
+//!             Err(nb::Error::Other(e)) => {
+//!                 // The error type specified by `timer.wait()` is `!`, which
+//!                 // means no error can actually occur. The Rust compiler
+//!                 // still forces us to provide this match arm, though.
+//!                 e
+//!             },
 //!             Err(nb::Error::WouldBlock) => continue,
 //!             Ok(()) => {
 //!                 timer.pause();
@@ -477,9 +519,9 @@
 //!
 //! use hal::prelude::*;
 //!
-//! fn flush(serial: &S, cb: &mut CircularBuffer) -> Result<(), S::Error>
+//! fn flush<S>(serial: &S, cb: &mut CircularBuffer) -> Result<(), S::Error>
 //! where
-//!     S: hal::Serial,
+//!     S: hal::serial::Write<u8>,
 //! {
 //!     loop {
 //!         if let Some(byte) = cb.peek() {
@@ -501,12 +543,12 @@
 //!
 //! // NOTE private
 //! static BUFFER: Mutex<CircularBuffer> = ..;
-//! static SERIAL: Mutex<impl hal::Serial> = ..;
+//! static SERIAL: Mutex<impl hal::serial::Write<u8>> = ..;
 //!
 //! impl BufferedSerial {
-//!     pub fn write(&self, byte: u8) {
+//!     pub fn write(&self, bytes: &[u8]) {
 //!         let mut buffer = BUFFER.lock();
-//!         for byte in byte {
+//!         for byte in bytes {
 //!             buffer.push(*byte).unwrap();
 //!         }
 //!     }
@@ -514,10 +556,9 @@
 //!     pub fn write_all(&self, bytes: &[u8]) {
 //!         let mut buffer = BUFFER.lock();
 //!         for byte in bytes {
-//!             cb.push(*byte).unwrap();
+//!             buffer.push(*byte).unwrap();
 //!         }
 //!     }
-//!
 //! }
 //!
 //! fn interrupt_handler() {