diff --git a/README.md b/README.md
index af6f014b..d5713f23 100644
--- a/README.md
+++ b/README.md
@@ -71,37 +71,69 @@ import play.api.libs.ws.JsonBodyWritables._
 To use a BodyReadable in a response, you must type the response explicitly:
 
 ```scala
-val responseBody: Future[scala.xml.Elem] = ws.url(...).get().map { response =>
-  response.body[scala.xml.Elem]
-}
+import scala.concurrent.{ ExecutionContext, Future }
+
+import play.api.libs.ws.StandaloneWSClient
+import play.api.libs.ws.XMLBodyReadables._ // required
+
+def handleXml(ws: StandaloneWSClient)(
+  implicit ec: ExecutionContext): Future[scala.xml.Elem] =
+  ws.url("...").get().map { response =>
+    response.body[scala.xml.Elem]
+  }
 ```
 
 or using Play-JSON:
 
 ```scala
-val jsonBody: Future[JsValue] = ws.url(...).get().map { response =>
-  response.body[JsValue]
-}
+import scala.concurrent.{ ExecutionContext, Future }
+
+import play.api.libs.json.JsValue
+import play.api.libs.ws.StandaloneWSClient
+
+import play.api.libs.ws.JsonBodyReadables._ // required
+
+def handleJsonResp(ws: StandaloneWSClient)(
+  implicit ec: ExecutionContext): Future[JsValue] =
+  ws.url("...").get().map { response =>
+    response.body[JsValue]
+  }
 ```
 
 Note that there is a special case: when you are streaming the response, then you should get the body as a Source:
 
 ```scala
-ws.url(...).stream().map { response =>
-   val source: Source[ByteString, NotUsed] = response.bodyAsSource
-}
+import scala.concurrent.ExecutionContext
+import akka.util.ByteString
+import akka.stream.scaladsl.Source
+import play.api.libs.ws.StandaloneWSClient
+
+def useWSStream(ws: StandaloneWSClient)(implicit ec: ExecutionContext) =
+  ws.url("...").stream().map { response =>
+     val source: Source[ByteString, _] = response.bodyAsSource
+     val _ = source // do something with source
+  }
 ```
 
 To POST, you should pass in a type which has an implicit class mapping of BodyWritable:
 
 ```scala
-val stringData = "Hello world"
-ws.url(...).post(stringData).map { response => ... }
+import scala.concurrent.ExecutionContext
+import play.api.libs.ws.DefaultBodyWritables._ // required
+
+def postExampleString(ws: play.api.libs.ws.StandaloneWSClient)(
+  implicit ec: ExecutionContext) = {
+  val stringData = "Hello world"
+  ws.url("...").post(stringData).map { response => /* do something */ }
+}
 ```
 
 You can also define your own custom BodyReadable: 
 
 ```scala
+import play.api.libs.ws.BodyReadable
+import play.api.libs.ws.ahc.StandaloneAhcWSResponse
+
 case class Foo(body: String)
 
 implicit val fooBodyReadable = BodyReadable[Foo] { response =>
@@ -114,9 +146,12 @@ implicit val fooBodyReadable = BodyReadable[Foo] { response =>
 or custom BodyWritable:
 
 ```scala
+import akka.util.ByteString
+import play.api.libs.ws.{ BodyWritable, InMemoryBody }
+
 implicit val writeableOf_Foo: BodyWritable[Foo] = {
   // https://tools.ietf.org/html/rfc6838#section-3.2
-  BodyWritable(foo => InMemoryBody(ByteString.fromString(foo.serialize)), application/vnd.company.category+foo)
+  BodyWritable(foo => InMemoryBody(ByteString.fromString(foo.toString)), "application/vnd.company.category+foo")
 }
 ```
 
@@ -234,10 +269,10 @@ object ScalaClient {
   }
 
   def call(wsClient: StandaloneWSClient): Future[Unit] = {
-    wsClient.url("http://www.google.com").get().map { response ⇒
+    wsClient.url("http://www.google.com").get().map { response =>
       val statusText: String = response.statusText
       val body = response.body[String]
-      println(s"Got a response $statusText")
+      println(s"Got a response $statusText: $body")
     }
   }
 }
@@ -299,19 +334,39 @@ Play WS implements [HTTP Caching](https://tools.ietf.org/html/rfc7234) through C
 To create a standalone AHC client that uses caching, pass in an instance of AhcHttpCache with a cache adapter to the underlying implementation.  For example, to use Caffeine as the underlying cache, you could use the following:
 
 ```scala
+import scala.concurrent.Future
+import java.util.concurrent.TimeUnit
+import com.github.benmanes.caffeine.cache.{ Caffeine, Ticker }
+
+import play.api.libs.ws.ahc.StandaloneAhcWSClient
+import play.api.libs.ws.ahc.cache.{
+  AhcHttpCache, Cache, EffectiveURIKey, ResponseEntry
+}
+
 class CaffeineHttpCache extends Cache {
-     val underlying = Caffeine.newBuilder()
-       .ticker(Ticker.systemTicker())
-       .expireAfterWrite(365, TimeUnit.DAYS)
-       .build[EffectiveURIKey, ResponseEntry]()
-
-  override def remove(key: EffectiveURIKey): Unit = underlying.invalidate(key)
-  override def put(key: EffectiveURIKey, entry: ResponseEntry): Unit = underlying.put(key, entry)
-  override def get(key: EffectiveURIKey): ResponseEntry = underlying.getIfPresent(key)
-  override def close(): Unit = underlying.cleanUp()
+  val underlying = Caffeine.newBuilder()
+    .ticker(Ticker.systemTicker())
+    .expireAfterWrite(365, TimeUnit.DAYS)
+    .build[EffectiveURIKey, ResponseEntry]()
+
+  def remove(key: EffectiveURIKey) =
+    Future.successful(Option(underlying.invalidate(key)))
+
+  def put(key: EffectiveURIKey, entry: ResponseEntry) =
+    Future.successful(underlying.put(key, entry))
+
+  def get(key: EffectiveURIKey) =
+    Future.successful(Option(underlying getIfPresent key ))
+
+  def close(): Unit = underlying.cleanUp()
+}
+
+def withCache(implicit m: akka.stream.Materializer): StandaloneAhcWSClient = {
+  implicit def ec = m.executionContext
+
+  val cache = new CaffeineHttpCache()
+  StandaloneAhcWSClient(httpCache = Some(new AhcHttpCache(cache)))
 }
-val cache = new CaffeineHttpCache()
-val client = StandaloneAhcWSClient(httpCache = AhcHttpCache(cache))   
 ```
 
 There are a number of guides that help with putting together Cache-Control headers:
diff --git a/bench/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSRequestBenchMapsBench.scala b/bench/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSRequestBenchMapsBench.scala
index da787afc..f2e70ba7 100644
--- a/bench/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSRequestBenchMapsBench.scala
+++ b/bench/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSRequestBenchMapsBench.scala
@@ -26,7 +26,9 @@ import play.api.libs.ws.StandaloneWSRequest
  * Compare your results before/after on your machine. Don't trust the ones in scaladoc.
  *
  * Sample benchmark results:
+ *
  * {{{
+ * // not compilable
  * > bench/jmh:run .*StandaloneAhcWSRequestBenchMapsBench
  * [info] Benchmark                                             (size)  Mode  Cnt    Score   Error  Units
  * [info] StandaloneAhcWSRequestBenchMapsBench.addHeaders            1  avgt       162.673          ns/op
diff --git a/integration-tests/src/test/scala/play/api/libs/ws/ahc/JsonRequestSpec.scala b/integration-tests/src/test/scala/play/api/libs/ws/ahc/JsonRequestSpec.scala
index 22fd351b..22f82975 100644
--- a/integration-tests/src/test/scala/play/api/libs/ws/ahc/JsonRequestSpec.scala
+++ b/integration-tests/src/test/scala/play/api/libs/ws/ahc/JsonRequestSpec.scala
@@ -11,11 +11,11 @@ import akka.stream.Materializer
 import akka.util.ByteString
 import org.mockito.Mockito.{ times, verify, when }
 import org.specs2.mock.Mockito
-import org.specs2.mock.Mockito.mock
+
 import org.specs2.mutable.Specification
 import org.specs2.specification.AfterAll
 import play.api.libs.json.{ JsString, JsValue, Json }
-import play.api.libs.ws.{ JsonBodyReadables, JsonBodyWritables, StandaloneWSResponse }
+import play.api.libs.ws.{ JsonBodyReadables, JsonBodyWritables }
 import play.libs.ws.DefaultObjectMapper
 import play.shaded.ahc.org.asynchttpclient.Response
 
diff --git a/play-ahc-ws-standalone/src/main/scala/play/api/libs/oauth/OAuth.scala b/play-ahc-ws-standalone/src/main/scala/play/api/libs/oauth/OAuth.scala
index 49f23e3e..4b5a8cf5 100644
--- a/play-ahc-ws-standalone/src/main/scala/play/api/libs/oauth/OAuth.scala
+++ b/play-ahc-ws-standalone/src/main/scala/play/api/libs/oauth/OAuth.scala
@@ -10,7 +10,11 @@ import play.shaded.oauth.oauth.signpost.exception.OAuthException
 import play.shaded.ahc.org.asynchttpclient.oauth.OAuthSignatureCalculator
 import play.shaded.ahc.org.asynchttpclient.{ Request, RequestBuilderBase, SignatureCalculator }
 import play.api.libs.ws.WSSignatureCalculator
-import play.shaded.ahc.org.asynchttpclient.oauth.{ ConsumerKey => AHCConsumerKey, RequestToken => AHCRequestToken }
+
+import play.shaded.ahc.org.asynchttpclient.oauth.{
+  ConsumerKey => AHCConsumerKey,
+  RequestToken => AHCRequestToken
+}
 
 /**
  * Library to access resources protected by OAuth 1.0a.
@@ -111,10 +115,24 @@ class OAuthCalculator(consumerKey: ConsumerKey, requestToken: RequestToken) exte
  *
  * Example:
  * {{{
- * import play.api.libs.oauth._
- * val consumerKey: ConsumerKey = ConsumerKey(twitterConsumerKey, twitterConsumerSecret)
- * val requestToken: RequestToken = RequestToken(accessTokenKey, accessTokenSecret)
- * WS.url("http://example.com/protected").sign(OAuthCalculator(consumerKey, requestToken)).get()
+ * import play.api.libs.oauth.{ ConsumerKey, OAuthCalculator, RequestToken }
+ * import play.api.libs.ws.ahc.StandaloneAhcWSClient
+ *
+ * def example(
+ *   twitterConsumerKey: String,
+ *   twitterConsumerSecret: String,
+ *   accessTokenKey: String,
+ *   accessTokenSecret: String,
+ *   ws: StandaloneAhcWSClient) = {
+ *   val consumerKey: ConsumerKey =
+ *     ConsumerKey(twitterConsumerKey, twitterConsumerSecret)
+ *
+ *   val requestToken: RequestToken =
+ *     RequestToken(accessTokenKey, accessTokenSecret)
+ *
+ *   ws.url("http://example.com/protected").
+ *     sign(OAuthCalculator(consumerKey, requestToken)).get()
+ * }
  * }}}
  */
 object OAuthCalculator {
diff --git a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSClient.scala b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSClient.scala
index 859f4dca..53af4df5 100644
--- a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSClient.scala
+++ b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StandaloneAhcWSClient.scala
@@ -194,12 +194,19 @@ object StandaloneAhcWSClient {
    * Typical usage:
    *
    * {{{
+   * import play.api.libs.ws.ahc.StandaloneAhcWSClient
+   *
+   * def example(someUrl: String)(implicit m: akka.stream.Materializer) = {
+   *   implicit def ec = m.executionContext
+   *
    *   val client = StandaloneAhcWSClient()
    *   val request = client.url(someUrl).get()
+   *
    *   request.foreach { response =>
-   *     doSomething(response)
+   *     //doSomething(response)
    *     client.close()
    *   }
+   * }
    * }}}
    *
    * @param config configuration settings
diff --git a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StreamedResponse.scala b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StreamedResponse.scala
index 9ebd884d..389fb399 100644
--- a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StreamedResponse.scala
+++ b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/StreamedResponse.scala
@@ -16,11 +16,20 @@ import play.shaded.ahc.org.asynchttpclient.HttpResponseBodyPart
  * Note that this is only usable with a stream call, i.e.
  *
  * {{{
- * class MyClass extends StreamedBodyReadable {
- *   ws.url("http://example.com").stream().map { response =>
- *      val source = response.body[Source[ByteString, NotUsed]]
- *      ...
- *   }
+ * import scala.concurrent.{ ExecutionContext, Future }
+ *
+ * import akka.util.ByteString
+ * import akka.stream.scaladsl.Source
+ *
+ * import play.api.libs.ws.DefaultBodyReadables._
+ * import play.api.libs.ws.ahc.StandaloneAhcWSClient
+ *
+ * class MyClass(ws: StandaloneAhcWSClient) {
+ *   def doIt(implicit ec: ExecutionContext): Future[String] =
+ *     ws.url("http://example.com").stream().map { response =>
+ *        val _ = response.body[Source[ByteString, _]]
+ *        ??? // process source to String
+ *     }
  * }
  * }}}
  */
diff --git a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/cache/Cache.scala b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/cache/Cache.scala
index cea54f86..a0fa50e0 100644
--- a/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/cache/Cache.scala
+++ b/play-ahc-ws-standalone/src/main/scala/play/api/libs/ws/ahc/cache/Cache.scala
@@ -12,16 +12,31 @@ import scala.concurrent.Future
  * Implementations can write adapters that map through to this trait, i.e.
  *
  * {{{
+ * import java.util.concurrent.TimeUnit
+ * import scala.concurrent.Future
+ *
+ * import com.github.benmanes.caffeine.cache.{ Caffeine, Ticker }
+ *
+ * import play.api.libs.ws.ahc.cache.{
+ *   Cache, EffectiveURIKey, ResponseEntry
+ * }
+ *
  * class CaffeineHttpCache extends Cache {
- *    val underlying = Caffeine.newBuilder()
- *      .ticker(Ticker.systemTicker())
- *      .expireAfterWrite(365, TimeUnit.DAYS)
- *      .build[EffectiveURIKey, ResponseEntry]()
- *
- *     override def remove(key: EffectiveURIKey) = Future.successful(Option(underlying.invalidate(key))
- *     override def put(key: EffectiveURIKey, entry: ResponseEntry) = Future.successful(underlying.put(key, entry))
- *     override def get(key: EffectiveURIKey) = Future.successful(underlying.getIfPresent(key))
- *     override def close(): Unit = underlying.cleanUp()
+ *   val underlying = Caffeine.newBuilder()
+ *     .ticker(Ticker.systemTicker())
+ *     .expireAfterWrite(365, TimeUnit.DAYS)
+ *     .build[EffectiveURIKey, ResponseEntry]()
+ *
+ *   def remove(key: EffectiveURIKey) =
+ *     Future.successful(Option(underlying.invalidate(key)))
+ *
+ *   def put(key: EffectiveURIKey, entry: ResponseEntry) =
+ *     Future.successful(underlying.put(key, entry))
+ *
+ *   def get(key: EffectiveURIKey) =
+ *     Future.successful(Option(underlying getIfPresent key ))
+ *
+ *   def close(): Unit = underlying.cleanUp()
  * }
  * }}}
  */
diff --git a/play-ahc-ws-standalone/src/test/scala/play/api/libs/ws/ahc/AhcWSRequestSpec.scala b/play-ahc-ws-standalone/src/test/scala/play/api/libs/ws/ahc/AhcWSRequestSpec.scala
index 6d4c137c..084814be 100644
--- a/play-ahc-ws-standalone/src/test/scala/play/api/libs/ws/ahc/AhcWSRequestSpec.scala
+++ b/play-ahc-ws-standalone/src/test/scala/play/api/libs/ws/ahc/AhcWSRequestSpec.scala
@@ -4,23 +4,24 @@
 
 package play.api.libs.ws.ahc
 
+import scala.collection.JavaConverters._
+import scala.concurrent.duration._
+
 import akka.actor.ActorSystem
-import akka.stream.ActorMaterializer
 import akka.stream.Materializer
 import akka.util.ByteString
+
 import org.specs2.execute.Result
 import org.specs2.mock.Mockito
 import org.specs2.mutable.Specification
 import org.specs2.specification.AfterAll
+
 import play.api.libs.oauth.{ ConsumerKey, RequestToken, OAuthCalculator }
 import play.api.libs.ws._
 import play.shaded.ahc.io.netty.handler.codec.http.HttpHeaderNames
 import play.shaded.ahc.org.asynchttpclient.Realm.AuthScheme
 import play.shaded.ahc.org.asynchttpclient.{ SignatureCalculator, Param, Request => AHCRequest }
 
-import scala.collection.JavaConverters._
-import scala.concurrent.duration._
-
 class AhcWSRequestSpec extends Specification with Mockito with AfterAll with DefaultBodyReadables with DefaultBodyWritables {
 
   sequential
diff --git a/play-ws-standalone-json/src/main/scala/play/api/libs/ws/JsonBodyReadables.scala b/play-ws-standalone-json/src/main/scala/play/api/libs/ws/JsonBodyReadables.scala
index 9bcf0552..a22f553b 100644
--- a/play-ws-standalone-json/src/main/scala/play/api/libs/ws/JsonBodyReadables.scala
+++ b/play-ws-standalone-json/src/main/scala/play/api/libs/ws/JsonBodyReadables.scala
@@ -17,7 +17,10 @@ trait JsonBodyReadables {
    * Converts a response body into Play JSON format:
    *
    * {{{
-   * val json = response.body[play.api.libs.json.JsValue]
+   * import play.api.libs.ws.StandaloneWSResponse
+   * import play.api.libs.ws.JsonBodyReadables._
+   *
+   * def json(r: StandaloneWSResponse) = r.body[play.api.libs.json.JsValue]
    * }}}
    */
   implicit val readableAsJson: BodyReadable[JsValue] = BodyReadable { response =>
diff --git a/play-ws-standalone-xml/src/main/scala/play/api/libs/ws/XMLBodyReadables.scala b/play-ws-standalone-xml/src/main/scala/play/api/libs/ws/XMLBodyReadables.scala
index f31694bf..3e3c052c 100644
--- a/play-ws-standalone-xml/src/main/scala/play/api/libs/ws/XMLBodyReadables.scala
+++ b/play-ws-standalone-xml/src/main/scala/play/api/libs/ws/XMLBodyReadables.scala
@@ -15,7 +15,12 @@ trait XMLBodyReadables {
    * Converts a response body into XML document:
    *
    * {{{
-   * val xml = response.body[scala.xml.Elem]
+   * import scala.xml.Elem
+   *
+   * import play.api.libs.ws.StandaloneWSResponse
+   * import play.api.libs.ws.XMLBodyReadables._
+   *
+   * def foo(resp: StandaloneWSResponse): Elem = resp.body[Elem]
    * }}}
    */
   implicit val readableAsXml: BodyReadable[Elem] = BodyReadable { response =>
diff --git a/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyReadables.scala b/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyReadables.scala
index 224c73eb..ade97a44 100644
--- a/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyReadables.scala
+++ b/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyReadables.scala
@@ -10,51 +10,65 @@ import akka.stream.scaladsl.Source
 import akka.util.ByteString
 
 /**
- * Defines common BodyReadable for a response backed by org.asynchttpclient.Response.
+ * Defines common BodyReadable for a response backed by `org.asynchttpclient.Response`.
  */
 trait DefaultBodyReadables {
 
   /**
-   * Converts a response body into an akka.util.ByteString:
+   * Converts a response body into an `akka.util.ByteString`:
    *
    * {{{
-   * val byteString = response.body[ByteString]
+   * import akka.util.ByteString
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def example(response: play.api.libs.ws.StandaloneWSResponse): ByteString =
+   *   response.body[ByteString]
    * }}}
    */
   implicit val readableAsByteString: BodyReadable[ByteString] = BodyReadable(_.bodyAsBytes)
 
   /**
-   * Converts a response body into a String.
+   * Converts a response body into a `String`.
    *
    * Note: this is only a best-guess effort and does not handle all content types. See
    * [[StandaloneWSResponse.body:String*]] for more information.
    *
    * {{{
-   * val string = response.body[String]
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def example(response: play.api.libs.ws.StandaloneWSResponse): String =
+   *   response.body[String]
    * }}}
    */
   implicit val readableAsString: BodyReadable[String] = BodyReadable(_.body)
 
   /**
-   * Converts a response body into a read only ByteBuffer.
+   * Converts a response body into a read only `ByteBuffer`.
    *
    * {{{
-   * val buffer = response.body[ByteBuffer]
+   * import java.nio.ByteBuffer
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def example(response: play.api.libs.ws.StandaloneWSResponse): ByteBuffer =
+   *   response.body[ByteBuffer]
    * }}}
    */
   implicit val readableAsByteBuffer: BodyReadable[ByteBuffer] = BodyReadable(_.bodyAsBytes.asByteBuffer)
 
   /**
-   * Converts a response body into Array[Byte].
+   * Converts a response body into `Array[Byte]`.
    *
    * {{{
-   * val byteArray = response.body[Array[Byte]]
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def example(response: play.api.libs.ws.StandaloneWSResponse): Array[Byte] =
+   *   response.body[Array[Byte]]
    * }}}
    */
   implicit val readableAsByteArray: BodyReadable[Array[Byte]] = BodyReadable(_.bodyAsBytes.toArray)
 
   /**
-   * Converts a response body into Source[ByteString, NotUsed].
+   * Converts a response body into `Source[ByteString, _]`.
    */
   implicit val readableAsSource: BodyReadable[Source[ByteString, _]] = BodyReadable(_.bodyAsSource)
 }
diff --git a/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyWritables.scala b/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyWritables.scala
index 244c05d3..dbd08c99 100644
--- a/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyWritables.scala
+++ b/play-ws-standalone/src/main/scala/play/api/libs/ws/DefaultBodyWritables.scala
@@ -19,10 +19,15 @@ import scala.compat.java8.FunctionConverters.asScalaFromSupplier
  * requests that take a body such as PUT, POST and PATCH.
  *
  * {{{
- * class MyClass extends DefaultBodyWritables {
- *   def postBody() = {
- *     val getBody: String = ...
- *     ws.url(...).post(getBody).map { response => ... }
+ * import scala.concurrent.ExecutionContext
+ *
+ * import play.api.libs.ws.StandaloneWSClient
+ * import play.api.libs.ws.DefaultBodyWritables._
+ *
+ * class MyClass(ws: StandaloneWSClient) {
+ *   def postBody()(implicit ec: ExecutionContext) = {
+ *     val getBody: String = "..."
+ *     ws.url("...").post(getBody).map { response => ??? }
  *   }
  * }
  * }}}
diff --git a/play-ws-standalone/src/main/scala/play/api/libs/ws/StandaloneWSResponse.scala b/play-ws-standalone/src/main/scala/play/api/libs/ws/StandaloneWSResponse.scala
index 1860fbab..1d963cf2 100644
--- a/play-ws-standalone/src/main/scala/play/api/libs/ws/StandaloneWSResponse.scala
+++ b/play-ws-standalone/src/main/scala/play/api/libs/ws/StandaloneWSResponse.scala
@@ -78,19 +78,33 @@ trait StandaloneWSResponse {
    * The simplest use case is
    *
    * {{{
-   * val responseBodyAsString: String = response.body[String]
+   * import play.api.libs.ws.StandaloneWSResponse
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def responseBodyAsString(response: StandaloneWSResponse): String =
+   *   response.body[String]
    * }}}
    *
    * But you can also render as JSON
    *
    * {{{
-   * val responseBodyAsJson: JsValue = response.body[JsValue]
+   * // not compilable: requires `play-ws-standalone-json` dependency
+   * import play.api.libs.json.JsValue
+   * import play.api.libs.ws.StandaloneWSResponse
+   *
+   * def responseBodyAsJson(response: StandaloneWSResponse): JsValue =
+   *   response.body[JsValue]
    * }}}
    *
-   * or as XML:
+   * or as binary:
    *
    * {{{
-   * val responseBodyAsByteString: ByteString = response.body[ByteString]
+   * import akka.util.ByteString
+   * import play.api.libs.ws.StandaloneWSResponse
+   * import play.api.libs.ws.DefaultBodyReadables._
+   *
+   * def responseBodyAsByteString(response: StandaloneWSResponse): ByteString =
+   *   response.body[ByteString]
    * }}}
    */
   def body[T: BodyReadable]: T = {
diff --git a/play-ws-standalone/src/main/scala/play/api/libs/ws/WSConfigParser.scala b/play-ws-standalone/src/main/scala/play/api/libs/ws/WSConfigParser.scala
index 64243dac..9e3caa00 100644
--- a/play-ws-standalone/src/main/scala/play/api/libs/ws/WSConfigParser.scala
+++ b/play-ws-standalone/src/main/scala/play/api/libs/ws/WSConfigParser.scala
@@ -18,7 +18,11 @@ import scala.concurrent.duration.Duration
  * You can create a client config from an application.conf file by running
  *
  * {{{
- *   val wsClientConfig = new WSConfigParser(ConfigFactory.load(), this.classLoader).parse()
+ * import play.api.libs.ws.WSConfigParser
+ * import com.typesafe.config.ConfigFactory
+ *
+ * val wsClientConfig = new WSConfigParser(
+ *   ConfigFactory.load(), this.getClass.getClassLoader).parse()
  * }}}
  */
 @Singleton
diff --git a/play-ws-standalone/src/main/scala/play/api/libs/ws/WSRequestFilter.scala b/play-ws-standalone/src/main/scala/play/api/libs/ws/WSRequestFilter.scala
index 64d76aaa..0f9a81d8 100644
--- a/play-ws-standalone/src/main/scala/play/api/libs/ws/WSRequestFilter.scala
+++ b/play-ws-standalone/src/main/scala/play/api/libs/ws/WSRequestFilter.scala
@@ -10,9 +10,11 @@ import scala.concurrent.Future
  * A request filter.  Override this trait to implement your own filters:
  *
  * {{{
+ * import play.api.libs.ws.{ WSRequestFilter, WSRequestExecutor }
+ *
  * class HeaderAppendingFilter(key: String, value: String) extends WSRequestFilter {
  *   override def apply(executor: WSRequestExecutor): WSRequestExecutor = {
- *     WSRequestExecutor(r => executor(r.withHeaders((key, value))))
+ *     WSRequestExecutor(r => executor(r.withHttpHeaders((key, value))))
  *   }
  * }
  * }}}
@@ -25,8 +27,10 @@ object WSRequestFilter {
    * Creates an adhoc filter from a function:
    *
    * {{{
+   * import play.api.libs.ws.{ WSRequestFilter, WSRequestExecutor }
+   *
    * val filter: WSRequestFilter = WSRequestFilter { e =>
-   *   WSRequestExecutor(r => e.apply(r.withQueryString("bed" -> "1")))
+   *   WSRequestExecutor(r => e.apply(r.withQueryStringParameters("bed" -> "1")))
    * }
    * }}}
    *
diff --git a/project/Dependencies.scala b/project/Dependencies.scala
index f2a99a14..d2a879a7 100644
--- a/project/Dependencies.scala
+++ b/project/Dependencies.scala
@@ -23,7 +23,7 @@ object Dependencies {
 
   val scalaJava8Compat = Seq("org.scala-lang.modules" %% "scala-java8-compat" % "0.9.0")
 
-  val playJsonVersion = "2.8.0"
+  val playJsonVersion = "2.8.1"
   val playJson = Seq("com.typesafe.play" %% "play-json" % playJsonVersion)
 
   val slf4jApi = Seq("org.slf4j" % "slf4j-api" % "1.7.29")
@@ -45,9 +45,9 @@ object Dependencies {
   val asyncHttpClientVersion = "2.10.4"
   val asyncHttpClient = Seq("org.asynchttpclient" % "async-http-client" % asyncHttpClientVersion)
 
-  val akkaVersion = "2.6.0"
+  val akkaVersion = "2.6.1"
   val akkaStreams = Seq("com.typesafe.akka" %% "akka-stream" % akkaVersion)
-  val akkaHttp = Seq("com.typesafe.akka" %% "akka-http" % "10.1.10")
+  val akkaHttp = Seq("com.typesafe.akka" %% "akka-http" % "10.1.11")
 
   val reactiveStreams = Seq("org.reactivestreams" % "reactive-streams" % "1.0.3")
 
diff --git a/project/build.properties b/project/build.properties
index 0f720116..edf4071f 100644
--- a/project/build.properties
+++ b/project/build.properties
@@ -1,4 +1,4 @@
 #
 # Copyright (C) 2009-2017 Lightbend Inc. <https://www.lightbend.com>
 #
-sbt.version=1.3.3
+sbt.version=1.3.4