More docs

8 files changed, 81 insertions, 28 deletions

diff --git a/docs/backends/akkahttp.rst b/docs/backends/akkahttp.rst
index 41e3a7c..53ebfda 100644
--- a/docs/backends/akkahttp.rst
+++ b/docs/backends/akkahttp.rst
@@ -1,3 +1,5 @@
+.. _akkahttp:
+
 ``AkkaHttpBackend``
 ===================
 
@@ -5,9 +7,7 @@ To use, add the following dependency to your project::
 
   "com.softwaremill.sttp" %% "akka-http-backend" % "0.0.20"
 
-This backend depends on `akka-http <http://doc.akka.io/docs/akka-http/current/scala/http/>`_.
-A fully **asynchronous** backend. Sending a request returns a response wrapped
-in a ``Future``.
+This backend depends on `akka-http <http://doc.akka.io/docs/akka-http/current/scala/http/>`_. A fully **asynchronous** backend. Sending a request returns a response wrapped in a ``Future``.
 
 Next you'll need to add an implicit value::
 
@@ -16,9 +16,7 @@ Next you'll need to add an implicit value::
   // or, if you'd like to use an existing actor system:
   implicit val sttpBackend = AkkaHttpBackend.usingActorSystem(actorSystem)
 
-This backend supports sending and receiving 
-`akka-streams <http://doc.akka.io/docs/akka/current/scala/stream/index.html>`_
-streams of type ``akka.stream.scaladsl.Source[ByteString, Any]``.
+This backend supports sending and receiving `akka-streams <http://doc.akka.io/docs/akka/current/scala/stream/index.html>`_ streams of type ``akka.stream.scaladsl.Source[ByteString, Any]``.
 
 To set the request body as a stream::
 
diff --git a/docs/backends/asynchttpclient.rst b/docs/backends/asynchttpclient.rst
index cd359b1..8408175 100644
--- a/docs/backends/asynchttpclient.rst
+++ b/docs/backends/asynchttpclient.rst
@@ -19,7 +19,7 @@ The responses are wrapped depending on the dependency chosen in either a:
 
 * standard Scala ``Future``
 * `Scalaz <https://github.com/scalaz/scalaz>`_ ``Task``. There's a transitive dependency on ``scalaz-concurrent``.
-* `Monix <https://monix.io`_ ``Task``. There's a transitive dependency on ``monix-eval``.
+* `Monix <https://monix.io>`_ ``Task``. There's a transitive dependency on ``monix-eval``.
 * Any type implementing the `Cats Effect <https://github.com/typelevel/cats-effect>`_ ``Async`` typeclass, such as ``cats.effect.IO``. There's a transitive dependency on ``cats-effect``.
 
 Next you'll need to add an implicit value::
diff --git a/docs/backends/custom.rst b/docs/backends/custom.rst
index 86d750a..4dd5208 100644
--- a/docs/backends/custom.rst
+++ b/docs/backends/custom.rst
@@ -1,11 +1,9 @@
+.. _custombackends:
+
 Custom backends, logging, metrics
 =================================
 
-It is also entirely possible to write your own backend (if so, please consider
-contributing!) or wrapping an existing one. You can even write completely 
-generic wrappers for any delegate backend, as each backend comes equipped
-with a monad for the response type. This brings the possibility to ``map`` and 
-``flatMap`` over responses. 
+It is also entirely possible to write custom own backend (if doing so, please consider contributing!) or wrapping an existing one. One can even write completely generic wrappers for any delegate backend, as each backend comes equipped with a monad for the response type. This brings the possibility to ``map`` and ``flatMap`` over responses. 
 
 Possible use-cases for wrapper-backend include:
  
@@ -13,7 +11,7 @@ Possible use-cases for wrapper-backend include:
 * capturing metrics
 * request signing (transforming the request before sending it to the delegate)
 
-To pass some context to wrapper-backends, requests can be *tagged*. Each 
-``RequestT`` instance contains a ``tags: Map[String, Any]`` field. This is unused
-by http, but can be used e.g. to pass a metric name or logging context.
+To pass some context to wrapper-backends, requests can be *tagged*. Each ``RequestT`` instance contains a ``tags: Map[String, Any]`` field. This is unused by http, but can be used e.g. to pass a metric name or logging context.
+
+Example backend logging
 
diff --git a/docs/backends/httpurlconnection.rst b/docs/backends/httpurlconnection.rst
index a196343..fdea9b0 100644
--- a/docs/backends/httpurlconnection.rst
+++ b/docs/backends/httpurlconnection.rst
@@ -1,8 +1,7 @@
 ``HttpURLConnectionBackend``
 ============================
 
-The default **synchronous** backend. Sending a request returns a response wrapped 
-in the identity type constructor, which is equivalent to no wrapper at all.
+The default **synchronous** backend. Sending a request returns a response wrapped in the identity type constructor, which is equivalent to no wrapper at all.
  
 To use, add an implicit value::
 
diff --git a/docs/backends/start_stop.rst b/docs/backends/start_stop.rst
index 6cd6f13..ed117a7 100644
--- a/docs/backends/start_stop.rst
+++ b/docs/backends/start_stop.rst
@@ -1,17 +1,9 @@
 Starting & cleaning up
 ======================
 
-In case of most backends, you should only instantiate a backend once per 
-application, as a backend typically allocates resources such as thread or
-connection pools.
+In case of most backends, you should only instantiate a backend once per application, as a backend typically allocates resources such as thread or connection pools.
 
-When ending the application, make sure to call ``backend.close()``, which will 
-free up resources used by the backend (if any). The close process might be 
-asynchronous, that is it can complete after the ``close()`` method returns.
+When ending the application, make sure to call ``backend.close()``, which will free up resources used by the backend (if any). The close process might be asynchronous, that is it can complete after the ``close()`` method returns.
 
-Note that only resources allocated by the backends are freed. For example,
-if you use the ``AkkaHttpBackend()`` the ``close()`` method will terminate the
-underlying actor system. However, if you have provided an existing actor system
-upon backend creation (``AkkaHttpBackend.usingActorSystem``), the ``close()`` 
-method will be a no-op. 
+Note that only resources allocated by the backends are freed. For example, if you use the ``AkkaHttpBackend()`` the ``close()`` method will terminate the underlying actor system. However, if you have provided an existing actor system upon backend creation (``AkkaHttpBackend.usingActorSystem``), the ``close()`` method will be a no-op. 
 
diff --git a/docs/backends/summary.rst b/docs/backends/summary.rst
index 6aa0446..36e50b0 100644
--- a/docs/backends/summary.rst
+++ b/docs/backends/summary.rst
@@ -1,6 +1,19 @@
+.. _backends_summary:
+
 Supported backends
 ==================
 
+sttp suports a number of synchornous and asynchronous backends. It's the backends that take care of managing connections, sending requests and receiving responses: sttp defines only the API to describe the requests to be send and handle the response data. It's the backends where all the heavy-lifting is done.
+
+Choosing the right backend depends on a number of factors: if you are using sttp to explore some data, or is it a production system; are you using a synchornous, blocking architecture or an asynchronous one; do you work mostly with Scala's ``Future``, or maybe you use some form of a ``Task`` abstraction; finally, if you want to stream requests/responses, or not.
+
+Each backend has two type parameters:
+
+* ``R[_]``, the type constructor in which responses are wrapped. That is, when you invoke ``send()`` on a request description, do you get a ``Response[_]`` directly, or is it wrapped in a ``Future`` or a ``Task``?
+* ``S``, the type of supported streams. If ``Nothing``, streaming is not supported. Otherwise, the given type can be used to send request bodies or receive response bodies.
+
+Below is a summary of all the backends. See the sections on individual backend implementations for more information.
+
 ================================ ============================ ================================================
 Class                            Result wrapper               Supported stream type
 ================================ ============================ ================================================
diff --git a/docs/backends/tagging.rst b/docs/backends/tagging.rst
new file mode 100644
index 0000000..15773ff
--- /dev/null
+++ b/docs/backends/tagging.rst
@@ -0,0 +1,9 @@
+Request tagging
+===============
+
+Each request contains a ``tags: Map[String, Any]`` map. This map can be used to tag the request with any backend-specific information, and isn't used in any way by sttp itself.
+
+Tags can be added to a request using the ``def tag(k: String, v: Any)`` method, and read using the ``def tag(k: String): Option[Any]`` method.
+
+Backends, or :ref:`backend wrappers <custombackends>` can use tags e.g. for logging, passing a metric name, using different connection pools, or even different delegate backends.
+
diff --git a/docs/backends/testing.rst b/docs/backends/testing.rst
new file mode 100644
index 0000000..0ac21c2
--- /dev/null
+++ b/docs/backends/testing.rst
@@ -0,0 +1,44 @@
+Testing
+=======
+
+If you need a stub backend for use in tests instead of a "real" backend (you 
+probably don't want to make HTTP calls during unit tests), you can use the
+``SttpBackendStub`` class. It allows specifying how the backend should respond
+to requests matching given predicates.
+
+A backend stub can be created using an instance of a "real" backend, or by
+explicitly giving the response wrapper monad and supported streams type.
+
+For example::
+
+  implicit val testingBackend = SttpBackendStub(HttpURLConnectionBackend())
+    .whenRequestMatches(_.uri.path.startsWith(List("a", "b")))
+    .thenRespond("Hello there!")
+    .whenRequestMatches(_.method == Method.POST)
+    .thenRespondServerError()
+      
+  val response1 = sttp.get(uri"http://example.org/a/b/c").send()
+  // response1.body will be Right("Hello there")
+  
+  val response2 = sttp.post(uri"http://example.org/d/e").send()
+  // response2.code will be 500
+
+However, this approach has one caveat: the responses are not type-safe. That
+is, the backend cannot match on or verify that the type included in the 
+response matches the response type requested.
+
+It is also possible to create a stub backend which delegates calls to another
+(possibly "real") backend if none of the specified predicates match a request.
+This can be useful during development, to partially stub a yet incomplete
+API with which we integrate::
+
+  implicit val testingBackend = SttpBackendStub.withFallback(HttpURLConnectionBackend())
+    .whenRequestMatches(_.uri.path.startsWith(List("a")))
+    .thenRespond("I'm a STUB!")
+      
+  val response1 = sttp.get(uri"http://api.internal/a").send()
+  // response1.body will be Right("I'm a STUB")
+  
+  val response2 = sttp.post(uri"http://api.internal/b").send()
+  // response2 will be whatever a "real" network call to api.internal/b returns
+