diff --git a/.travis.yml b/.travis.yml
index f240e47..fe53702 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -21,8 +21,9 @@ before_script:
 
 script:
 - |
-    travis-cargo build && travis-cargo test && travis-cargo bench &&
-    travis-cargo build -- --features tls && travis-cargo test -- --features tls && travis-cargo bench -- --features tls
+    travis-cargo build -- --features tls && travis-cargo test -- --features tls && travis-cargo bench -- --features tls &&
+    rustdoc --test README.md -L target/debug/deps -L target/debug &&
+    travis-cargo build && travis-cargo test && travis-cargo bench
 
 after_success:
 - travis-cargo coveralls --no-sudo
diff --git a/README.md b/README.md
index 4c51613..515a2a5 100644
--- a/README.md
+++ b/README.md
@@ -41,19 +41,21 @@ tarpc = { git = "https://github.com/google/tarpc" }
 tarpc-plugins = { git = "https://github.com/google/tarpc" }
 ```
 
-## Example
-```rust
+## Example: Sync
+
+tarpc has two APIs: `sync` for blocking code and `future` for asynchronous
+code. Here's how to use the sync api.
+
+```rust,no_run
 // required by `FutureClient` (not used directly in this example)
 #![feature(conservative_impl_trait, plugin)]
 #![plugin(tarpc_plugins)]
 
-extern crate futures;
 #[macro_use]
 extern crate tarpc;
-extern crate tokio_core;
 
 use tarpc::{client, server};
-use tarpc::client::sync::Connect;
+use tarpc::client::sync::ClientExt;
 use tarpc::util::{FirstSocketAddr, Never};
 
 service! {
@@ -92,7 +94,7 @@ races! See the `tarpc_examples` package for more examples.
 
 Here's the same service, implemented using futures.
 
-```rust
+```rust,no_run
 #![feature(conservative_impl_trait, plugin)]
 #![plugin(tarpc_plugins)]
 
@@ -162,7 +164,7 @@ Both TLS streams and TCP streams are supported in the same binary when the `tls`
 However, if you are working with both stream types, ensure that you use the TLS clients with TLS
 servers and TCP clients with TCP servers.
 
-```rust
+```rust,no_run
 #![feature(conservative_impl_trait, plugin)]
 #![plugin(tarpc_plugins)]
 
@@ -188,7 +190,7 @@ struct HelloServer;
 impl FutureService for HelloServer {
     type HelloFut = Result<String, Never>;
 
-    fn hello(&mut self, name: String) -> Self::HelloFut {
+    fn hello(&self, name: String) -> Self::HelloFut {
         Ok(format!("Hello, {}!", name))
     }
 }
@@ -208,7 +210,7 @@ fn main() {
                           .unwrap();
     let options = client::Options::default()
                                    .handle(reactor.handle())
-                                   .tls(client::tls::Context::new("foobar.com").unwrap()));
+                                   .tls(client::tls::Context::new("foobar.com").unwrap());
     reactor.run(FutureClient::connect(addr, options)
             .map_err(tarpc::Error::from)
             .and_then(|client| client.hello("Mom".to_string()))
@@ -235,7 +237,7 @@ E>`. The error type defaults to `tarpc::util::Never` (a wrapper for `!` which im
 `std::error::Error`) if no error type is explicitly specified in the `service!` macro invocation. An
 error type can be specified like so:
 
-```rust
+```rust,ignore
 use tarpc::util::Message;
 
 service! {
@@ -251,23 +253,19 @@ the macro automatically chooses `tarpc::util::Never` as the error type.
 
 The above declaration would produce the following synchronous service trait:
 
-```rust
-impl SyncService for HelloServer {
-    fn hello(&self, name: String) -> Result<String, Message> {
-        Ok(format!("Hello, {}!", name))
-    }
+```rust,ignore
+trait SyncService {
+    fn hello(&self, name: String) -> Result<String, Message>;
 }
 ```
 
 and the following future-based trait:
 
-```rust
-impl FutureService for HelloServer {
-    type HelloFut = Result<String, Message>;
+```rust,ignore
+trait FutureService {
+    type HelloFut = IntoFuture<String, Message>;
 
-    fn hello(&mut self, name: String) -> Self::HelloFut {
-        Ok(format!("Hello, {}!", name))
-    }
+    fn hello(&mut self, name: String) -> Self::HelloFut;
 }
 ```
 
diff --git a/hooks/pre-push b/hooks/pre-push
index 0d8d52a..1ad8b55 100755
--- a/hooks/pre-push
+++ b/hooks/pre-push
@@ -42,15 +42,15 @@ SUCCESS="${GREEN}ok${NC}"
 printf "${PREFIX} Clean working copy ... "
 git diff --exit-code &>/dev/null
 if [ "$?" == 0 ]; then
-	printf "${SUCCESS}\n"
+    printf "${SUCCESS}\n"
 else
-	if [ "${TARPC_ALLOW_DIRTY}" == "1" ]
-	then
-		printf "${SKIPPED}\n"
-	else
-		printf "${FAILURE}\n"
-		exit 1
-	fi
+    if [ "${TARPC_ALLOW_DIRTY}" == "1" ]
+    then
+        printf "${SKIPPED}\n"
+    else
+        printf "${FAILURE}\n"
+        exit 1
+    fi
 fi
 
 PREPUSH_RESULT=0
@@ -59,74 +59,74 @@ PREPUSH_RESULT=0
 # 1 - cargo command to run (build/test)
 # 2 - rust toolchain (nightly/stable/beta)
 run_cargo() {
-	if [ "$1" == "build" ]; then
-		VERB=Building
+    if [ "$1" == "build" ]; then
+        VERB=Building
     elif [ "$1" == "test" ]; then
-		VERB=Testing
+        VERB=Testing
     else
         VERB=Benching
-	fi
-	if [ "$2" != "" ]; then
-		printf "${PREFIX} $VERB on $2... "
-                if [ "$2" != "nightly" ]; then
-                    rustup run $2 cargo $1 &>/dev/null
-                else
-                    rustup run nightly cargo $1 --features unstable &>/dev/null
-                    rustup run nightly cargo $1 --features unstable,tls &>/dev/null
-                fi
-	else
-		printf "${PREFIX} $VERB... "
-		cargo $1 &>/dev/null
-		cargo $1 --features tls &>/dev/null
-	fi
-	if [ "$?" != "0" ]; then
-		printf "${FAILURE}\n"
-		PREPUSH_RESULT=1
-	else
-		printf "${SUCCESS}\n"
-	fi
+    fi
+    if [ "$2" != "" ]; then
+        printf "${PREFIX} $VERB on $2... "
+        if [ "$2" != "nightly" ]; then
+            rustup run $2 cargo $1 &>/dev/null
+        else
+            rustup run nightly cargo $1 --features unstable &>/dev/null
+            rustup run nightly cargo $1 --features unstable,tls &>/dev/null
+        fi
+    else
+        printf "${PREFIX} $VERB... "
+        cargo $1 &>/dev/null
+        cargo $1 --features tls &>/dev/null
+    fi
+    if [ "$?" != "0" ]; then
+        printf "${FAILURE}\n"
+        PREPUSH_RESULT=1
+    else
+        printf "${SUCCESS}\n"
+    fi
 }
 
 TOOLCHAIN_RESULT=0
 check_toolchain() {
-	printf "${PREFIX} Checking for $1 toolchain ... "
-	if [[ $(rustup toolchain list) =~ $1 ]]; then
-		printf "${SUCCESS}\n"
-	else
-		TOOLCHAIN_RESULT=1
-		PREPUSH_RESULT=1
-		printf "${FAILURE}\n"
-	fi
+    printf "${PREFIX} Checking for $1 toolchain ... "
+    if [[ $(rustup toolchain list) =~ $1 ]]; then
+        printf "${SUCCESS}\n"
+    else
+        TOOLCHAIN_RESULT=1
+        PREPUSH_RESULT=1
+        printf "${FAILURE}\n"
+    fi
 }
 
 printf "${PREFIX} Checking for rustup or current toolchain directive... "
 command -v rustup &>/dev/null
 if [ "$?" == 0 ] && [ "${TARPC_USE_CURRENT_TOOLCHAIN}" == "" ]; then
-	printf "${SUCCESS}\n"
+    printf "${SUCCESS}\n"
 
-	check_toolchain stable
-	check_toolchain beta
-	check_toolchain nightly
-	if [ ${TOOLCHAIN_RESULT} == 1 ]; then
-		exit 1
-	fi
+    check_toolchain stable
+    check_toolchain beta
+    check_toolchain nightly
+    if [ ${TOOLCHAIN_RESULT} == 1 ]; then
+        exit 1
+    fi
 
-	run_cargo build stable
-	run_cargo build beta
-	run_cargo build nightly
+    run_cargo build stable
+    run_cargo build beta
+    run_cargo build nightly
 
-	# We still rely on some nightly stuff for tests
-	run_cargo test nightly
+    # We still rely on some nightly stuff for tests
+    run_cargo test nightly
 else
-        if [ "${TARPC_USE_CURRENT_TOOLCHAIN}" == "" ]; then
-              printf "${YELLOW}NOT FOUND${NC}\n"
-              printf "${WARNING} Falling back to current toolchain: $(rustc -V)\n"
-        else
-              printf "${SUCCESS}\n"
-        fi
+    if [ "${TARPC_USE_CURRENT_TOOLCHAIN}" == "" ]; then
+        printf "${YELLOW}NOT FOUND${NC}\n"
+        printf "${WARNING} Falling back to current toolchain: $(rustc -V)\n"
+    else
+        printf "${SUCCESS}\n"
+    fi
 
     run_cargo build
-	run_cargo test
+    run_cargo test
     run_cargo bench
 fi