diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
index 59498fadd6..151a302168 100644
--- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
@@ -148,7 +148,7 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "POST"
     }
   }
-  "0mapRouteResponse" in {
+  "0mapRouteResult" in {
     val rejectAll = // not particularly useful directive
       mapRouteResult {
         case _ => Rejected(List(AuthorizationFailedRejection))
@@ -192,4 +192,103 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "prefix:test"
     }
   }
+  "cancelRejections-filter-example" in {
+    def isMethodRejection: Rejection => Boolean = {
+      case MethodRejection(_) => true
+      case _                  => false
+    }
+
+    val route =
+      cancelRejections(isMethodRejection) {
+        post {
+          complete("Result")
+        }
+      }
+
+    Get("/") ~> route ~> check {
+      rejections shouldEqual Nil
+      handled shouldEqual false
+    }
+  }
+  "cancelRejection-example" in {
+    val route =
+      cancelRejection(MethodRejection(HttpMethods.POST)) {
+        post {
+          complete("Result")
+        }
+      }
+
+    Get("/") ~> route ~> check {
+      rejections shouldEqual Nil
+      handled shouldEqual false
+    }
+  }
+  "extractRequest-example" in {
+    val route =
+      extractRequest { request =>
+        complete(s"Request method is ${request.method.name} and content-type is ${request.entity.contentType}")
+      }
+
+    Post("/", "text") ~> route ~> check {
+      responseAs[String] shouldEqual "Request method is POST and content-type is text/plain; charset=UTF-8"
+    }
+    Get("/") ~> route ~> check {
+      responseAs[String] shouldEqual "Request method is GET and content-type is none/none"
+    }
+  }
+  "extractUri-example" in {
+    val route =
+      extractUri { uri =>
+        complete(s"Full URI: $uri")
+      }
+
+    Get("/") ~> route ~> check {
+      // tests are executed with the host assumed to be "example.com"
+      responseAs[String] shouldEqual "Full URI: http://example.com/"
+    }
+    Get("/test") ~> route ~> check {
+      responseAs[String] shouldEqual "Full URI: http://example.com/test"
+    }
+  }
+  "mapUnmatchedPath-example" in {
+    def ignore456(path: Uri.Path) = path match {
+      case s @ Uri.Path.Segment(head, tail) if head.startsWith("456") =>
+        val newHead = head.drop(3)
+        if (newHead.isEmpty) tail
+        else s.copy(head = head.drop(3))
+      case _ => path
+    }
+    val ignoring456 = mapUnmatchedPath(ignore456)
+
+    val route =
+      pathPrefix("123") {
+        ignoring456 {
+          path("abc") {
+            complete(s"Content")
+          }
+        }
+      }
+
+    Get("/123/abc") ~> route ~> check {
+      responseAs[String] shouldEqual "Content"
+    }
+    Get("/123456/abc") ~> route ~> check {
+      responseAs[String] shouldEqual "Content"
+    }
+  }
+  "extractUnmatchedPath-example" in {
+    val route =
+      pathPrefix("abc") {
+        extractUnmatchedPath { remaining =>
+          complete(s"Unmatched: '$remaining'")
+        }
+      }
+
+    Get("/abc") ~> route ~> check {
+      responseAs[String] shouldEqual "Unmatched: ''"
+    }
+    Get("/abc/456") ~> route ~> check {
+      responseAs[String] shouldEqual "Unmatched: '/456'"
+    }
+  }
 }
diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
index e593ef777a..3e8ac7850a 100644
--- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
+++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
@@ -31,7 +31,7 @@ class FutureDirectivesExamplesSpec extends RoutingSpec {
   }))
   implicit val responseTimeout = Timeout(2, TimeUnit.SECONDS)
 
-  "example-1" in {
+  "onComplete" in {
     def divide(a: Int, b: Int): Future[Int] = Future {
       a / b
     }
@@ -54,7 +54,7 @@ class FutureDirectivesExamplesSpec extends RoutingSpec {
     }
   }
 
-  "example-2" in {
+  "onSuccess" in {
     val route =
       path("success") {
         onSuccess(Future { "Ok" }) { extraction =>
@@ -77,7 +77,7 @@ class FutureDirectivesExamplesSpec extends RoutingSpec {
     }
   }
 
-  "example-3" in {
+  "completeOrRecoverWith" in {
     val route =
       path("success") {
         completeOrRecoverWith(Future { "Ok" }) { extraction =>
diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
index a9b470ff0c..ff6d644c3e 100644
--- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
+++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
@@ -11,7 +11,7 @@ import StatusCodes._
 
 class HostDirectivesExamplesSpec extends RoutingSpec {
 
-  "extract-hostname" in {
+  "extractHost" in {
     val route =
       extractHost { hn =>
         complete(s"Hostname: $hn")
diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
index ff90bda276..3f6daf6f6d 100644
--- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
@@ -4,12 +4,13 @@
 
 package docs.http.scaladsl.server
 package directives
-/*
+
 import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
 import akka.http.scaladsl.model._
 import spray.json.DefaultJsonProtocol
 import headers._
 import StatusCodes._
+import MediaTypes.`application/json`
 
 //# person-case-class
 case class Person(name: String, favoriteNumber: Int)
@@ -37,7 +38,7 @@ class MarshallingDirectivesExamplesSpec extends RoutingSpec {
       }
   }
 
-  "example-produce-with-json" in {
+  "example-completeWith-with-json" in {
     import PersonJsonSupport._
 
     val findPerson = (f: Person => Unit) => {
@@ -49,13 +50,13 @@ class MarshallingDirectivesExamplesSpec extends RoutingSpec {
     }
 
     val route = get {
-      produce(instanceOf[Person]) { completionFunction => ctx => findPerson(completionFunction) }
+      completeWith(instanceOf[Person]) { completionFunction => findPerson(completionFunction) }
     }
 
     Get("/") ~> route ~> check {
       mediaType shouldEqual `application/json`
-      responseAs[String] must contain(""""name": "Jane"""")
-      responseAs[String] must contain(""""favoriteNumber": 42""")
+      responseAs[String] should include(""""name": "Jane"""")
+      responseAs[String] should include(""""favoriteNumber": 42""")
     }
   }
 
@@ -77,9 +78,8 @@ class MarshallingDirectivesExamplesSpec extends RoutingSpec {
     Post("/", HttpEntity(`application/json`, """{ "name": "Jane", "favoriteNumber" : 42 }""")) ~>
       route ~> check {
         mediaType shouldEqual `application/json`
-        responseAs[String] must contain(""""name": "Jane"""")
-        responseAs[String] must contain(""""favoriteNumber": 42""")
+        responseAs[String] should include(""""name": "Jane"""")
+        responseAs[String] should include(""""favoriteNumber": 42""")
       }
   }
 }
-*/ 
\ No newline at end of file
diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
index 21557bf983..426751cb6b 100644
--- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
@@ -4,80 +4,22 @@
 
 package docs.http.scaladsl.server
 package directives
-/*
+
 import akka.http.scaladsl.model._
 import akka.http.scaladsl.server._
 import headers._
 
 class MiscDirectivesExamplesSpec extends RoutingSpec {
-  "cancelAllRejections-example" in {
-    def isMethodRejection: Rejection => Boolean = {
-      case MethodRejection(_) => true
-      case _                  => false
-    }
 
-    val route =
-      cancelAllRejections(isMethodRejection) {
-        post {
-          complete("Result")
-        }
-      }
-
-    Get("/") ~> route ~> check {
-      rejections shouldEqual Nil
-      handled shouldEqual false
-    }
-  }
-  "cancelRejection-example" in {
-    val route =
-      cancelRejection(MethodRejection(HttpMethods.POST)) {
-        post {
-          complete("Result")
-        }
-      }
-
-    Get("/") ~> route ~> check {
-      rejections shouldEqual Nil
-      handled shouldEqual false
-    }
-  }
-  "clientIP-example" in {
-    val route = clientIP { ip =>
+  "extractClientIP-example" in {
+    val route = extractClientIP { ip =>
       complete("Client's ip is " + ip.toOption.map(_.getHostAddress).getOrElse("unknown"))
     }
 
-    Get("/").withHeaders(`Remote-Address`("192.168.3.12")) ~> route ~> check {
+    Get("/").withHeaders(`Remote-Address`(RemoteAddress("192.168.3.12"))) ~> route ~> check {
       responseAs[String] shouldEqual "Client's ip is 192.168.3.12"
     }
   }
-  "jsonpWithParameter-example" in {
-    case class Test(abc: Int)
-    object TestProtocol {
-      import spray.json.DefaultJsonProtocol._
-      implicit val testFormat = jsonFormat(Test, "abc")
-    }
-    val route =
-      jsonpWithParameter("jsonp") {
-        import TestProtocol._
-        import spray.httpx.SprayJsonSupport._
-        complete(Test(456))
-      }
-
-    Get("/?jsonp=result") ~> route ~> check {
-      responseAs[String] shouldEqual
-        """result({
-          |  "abc": 456
-          |})""".stripMarginWithNewline("\n")
-      contentType shouldEqual MediaTypes.`application/javascript`.withCharset(HttpCharsets.`UTF-8`)
-    }
-    Get("/") ~> route ~> check {
-      responseAs[String] shouldEqual
-        """{
-          |  "abc": 456
-          |}""".stripMarginWithNewline("\n")
-      contentType shouldEqual ContentTypes.`application/json`
-    }
-  }
   "rejectEmptyResponse-example" in {
     val route = rejectEmptyResponse {
       path("even" / IntNumber) { i =>
@@ -113,77 +55,9 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
       responseAs[String] shouldEqual "request entity empty"
     }
   }
-  "requestInstance-example" in {
-    val route =
-      requestInstance { request =>
-        complete(s"Request method is ${request.method} and length is ${request.entity.data.length}")
-      }
-
-    Post("/", "text") ~> route ~> check {
-      responseAs[String] shouldEqual "Request method is POST and length is 4"
-    }
-    Get("/") ~> route ~> check {
-      responseAs[String] shouldEqual "Request method is GET and length is 0"
-    }
-  }
-  "requestUri-example" in {
-    val route =
-      requestUri { uri =>
-        complete(s"Full URI: $uri")
-      }
-
-    Get("/") ~> route ~> check {
-      // tests are executed with the host assumed to be "example.com"
-      responseAs[String] shouldEqual "Full URI: http://example.com/"
-    }
-    Get("/test") ~> route ~> check {
-      responseAs[String] shouldEqual "Full URI: http://example.com/test"
-    }
-  }
-  "rewriteUnmatchedPath-example" in {
-    def ignore456(path: Uri.Path) = path match {
-      case s @ Uri.Path.Segment(head, tail) if head.startsWith("456") =>
-        val newHead = head.drop(3)
-        if (newHead.isEmpty) tail
-        else s.copy(head = head.drop(3))
-      case _ => path
-    }
-    val ignoring456 = rewriteUnmatchedPath(ignore456)
-
-    val route =
-      pathPrefix("123") {
-        ignoring456 {
-          path("abc") {
-            complete(s"Content")
-          }
-        }
-      }
-
-    Get("/123/abc") ~> route ~> check {
-      responseAs[String] shouldEqual "Content"
-    }
-    Get("/123456/abc") ~> route ~> check {
-      responseAs[String] shouldEqual "Content"
-    }
-  }
-  "unmatchedPath-example" in {
-    val route =
-      pathPrefix("abc") {
-        unmatchedPath { remaining =>
-          complete(s"Unmatched: '$remaining'")
-        }
-      }
-
-    Get("/abc") ~> route ~> check {
-      responseAs[String] shouldEqual "Unmatched: ''"
-    }
-    Get("/abc/456") ~> route ~> check {
-      responseAs[String] shouldEqual "Unmatched: '/456'"
-    }
-  }
   "validate-example" in {
     val route =
-      requestUri { uri =>
+      extractUri { uri =>
         validate(uri.path.toString.size < 5, s"Path too long: '${uri.path.toString}'") {
           complete(s"Full URI: $uri")
         }
@@ -197,4 +71,3 @@ class MiscDirectivesExamplesSpec extends RoutingSpec {
     }
   }
 }
-*/ 
\ No newline at end of file
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejection.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejection.rst
index 0337d1d451..2a613554df 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejection.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejection.rst
@@ -19,5 +19,5 @@ Description
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0cancelRejection
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: cancelRejection-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejections.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejections.rst
index 1d348fad54..9722aa60ca 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejections.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/cancelRejections.rst
@@ -19,5 +19,5 @@ Description
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0cancelRejections
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: cancelRejections-filter-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extract.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extract.rst
index 2d8ec6851d..2c92163338 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extract.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extract.rst
@@ -23,5 +23,5 @@ See :ref:`ProvideDirectives` for an overview of similar directives.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
    :snippet: 0extract
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractRequest.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractRequest.rst
index 860f88170a..c6f7241ef4 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractRequest.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractRequest.rst
@@ -3,7 +3,7 @@
 extractRequest
 ==============
 
-...
+Extracts the complete ``HttpRequest`` instance.
 
 Signature
 ---------
@@ -14,10 +14,12 @@ Signature
 Description
 -----------
 
-...
+Use ``extractRequest`` to extract just the complete URI of the request. Usually there's little use of
+extracting the complete request because extracting of most of the aspects of HttpRequests is handled by specialized
+directives. See :ref:`Request Directives`.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0extractRequest
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: extractRequest-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUnmatchedPath.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUnmatchedPath.rst
index 3475fbd2af..f39280c3c0 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUnmatchedPath.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUnmatchedPath.rst
@@ -3,7 +3,7 @@
 extractUnmatchedPath
 ====================
 
-...
+Extracts the unmatched path from the request context.
 
 Signature
 ---------
@@ -14,10 +14,14 @@ Signature
 Description
 -----------
 
-...
+The ``extractUnmatchedPath`` directive extracts the remaining path that was not yet matched by any of the :ref:`PathDirectives`
+(or any custom ones that change the unmatched path field of the request context). You can use it for building directives
+that handle complete suffixes of paths (like the ``getFromDirectory`` directives and similar ones).
+
+Use ``mapUnmatchedPath`` to change the value of the unmatched path.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0extractUnmatchedPath
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: extractUnmatchedPath-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUri.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUri.rst
index 9858fd59da..3b8b51bd66 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUri.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/extractUri.rst
@@ -3,7 +3,7 @@
 extractUri
 ==========
 
-...
+Access the full URI of the request.
 
 Signature
 ---------
@@ -14,10 +14,11 @@ Signature
 Description
 -----------
 
-...
+Use :ref:`SchemeDirectives`, :ref:`HostDirectives`, :ref:`PathDirectives`,  and :ref:`ParameterDirectives` for more
+targeted access to parts of the URI.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0extractUri
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: extractUri-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResult.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResult.rst
index 854f42c1d7..68feb84ef3 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResult.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResult.rst
@@ -22,5 +22,5 @@ See :ref:`Result Transformation Directives` for similar directives.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
    :snippet: 0mapRouteResult
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapUnmatchedPath.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapUnmatchedPath.rst
index c2706a7537..0f7807baa0 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapUnmatchedPath.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapUnmatchedPath.rst
@@ -3,7 +3,7 @@
 mapUnmatchedPath
 ================
 
-...
+Transforms the unmatchedPath field of the request context for inner routes.
 
 Signature
 ---------
@@ -14,10 +14,13 @@ Signature
 Description
 -----------
 
-...
+The ``mapUnmatchedPath`` directive is used as a building block for writing :ref:`Custom Directives`. You can use it
+for implementing custom path matching directives.
+
+Use ``extractUnmatchedPath`` for extracting the current value of the unmatched path.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0mapUnmatchedPath
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
+   :snippet: mapUnmatchedPath-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst
index 6f75cb9969..5233fd5b88 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst
@@ -19,5 +19,5 @@ Description
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
-   :snippet: 0encodeResponseWith
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: encodeResponseWith
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formFields.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formFields.rst
index bf28bfce9d..7b100d8e84 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formFields.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formFields.rst
@@ -92,7 +92,7 @@ to provide a ``Deserializer[Option[BodyPart], T]``.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FormFieldDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FormFieldDirectivesExamplesSpec.scala
    :snippet: formFields
 
 For more examples about the way how fields can specified see the examples for the ``parameters`` directive.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/completeOrRecoverWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/completeOrRecoverWith.rst
index b7b7617d91..76853bf4e6 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/completeOrRecoverWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/completeOrRecoverWith.rst
@@ -3,7 +3,8 @@
 completeOrRecoverWith
 =====================
 
-...
+Completes the request with the result of the computation given as argument of type ``Future[T]`` by marshalling it
+with the implicitly given ``ToResponseMarshaller[T]``. Runs the inner route if the ``Future`` computation fails.
 
 Signature
 ---------
@@ -14,10 +15,15 @@ Signature
 Description
 -----------
 
-...
+If the future succeeds the request is completed using the value's marshaller (this directive therefore
+requires a marshaller for the future's parameter type to be implicitly available). The execution of the inner
+route passed to this directive is only executed if the given future completed with a failure,
+exposing the reason of failure as a extraction of type ``Throwable``.
+
+To handle the successful case manually as well, use the :ref:`-onComplete-` directive, instead.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
-   :snippet: 0completeOrRecoverWith
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
+   :snippet: completeOrRecoverWith
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onComplete.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onComplete.rst
index 8c62e96caf..f155604b73 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onComplete.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onComplete.rst
@@ -3,7 +3,8 @@
 onComplete
 ==========
 
-...
+Evaluates its parameter of type ``Future[T]``, and once the ``Future`` has been completed, extracts its
+result as a value of type ``Try[T]`` and passes it to the inner route.
 
 Signature
 ---------
@@ -14,10 +15,14 @@ Signature
 Description
 -----------
 
-...
+The evaluation of the inner route passed to a onComplete directive is deferred until the given future
+has completed and provided with a extraction of type ``Try[T]``.
+
+To handle the ``Failure`` case automatically and only work with the result value, use :ref:`-onSuccess-`.
+To complete with a successful result automatically and just handle the failure result, use :ref:`-completeOrRecoverWith-`, instead.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
-   :snippet: 0onComplete
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
+   :snippet: onComplete
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onSuccess.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onSuccess.rst
index 449dd71928..1ce09fe71e 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onSuccess.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/future-directives/onSuccess.rst
@@ -3,7 +3,8 @@
 onSuccess
 =========
 
-...
+Evaluates its parameter of type ``Future[T]``, and once the ``Future`` has been completed successfully,
+extracts its result as a value of type ``T`` and passes it to the inner route.
 
 Signature
 ---------
@@ -14,10 +15,14 @@ Signature
 Description
 -----------
 
-...
+The execution of the inner route passed to a onSuccess directive is deferred until the given future
+has completed successfully, exposing the future's value as a extraction of type ``T``. If the future
+fails its failure throwable is bubbled up to the nearest ``ExceptionHandler``.
+
+To handle the ``Failure`` case manually as well, use :ref:`-onComplete-`, instead.
 
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
-   :snippet: 0onSuccess
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FutureDirectivesExamplesSpec.scala
+   :snippet: onSuccess
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValue.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValue.rst
index 3e3efc5936..5c03fae9ec 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValue.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValue.rst
@@ -26,5 +26,5 @@ syntactic alternative.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
    :snippet: headerValue-0
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByName.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByName.rst
index 6b245fdba5..25bf1768d9 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByName.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByName.rst
@@ -21,5 +21,5 @@ handling when the header is missing use the :ref:`-optionalHeaderValueByName-` d
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
    :snippet: headerValueByName-0
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByType.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByType.rst
index 200ab57339..e936eda4a9 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByType.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValueByType.rst
@@ -28,5 +28,5 @@ directive instead.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
    :snippet: headerValueByType-0
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValuePF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValuePF.rst
index 2cc2d63528..f37692d04b 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValuePF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/headerValuePF.rst
@@ -22,5 +22,5 @@ any header the request is rejected as "NotFound".
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
    :snippet: headerValuePF-0
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst
index 80f096ec5a..1bf3cea2de 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst
@@ -26,5 +26,5 @@ an ``Option`` value instead of rejecting the request if no matching header could
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HeaderDirectivesExamplesSpec.scala
    :snippet: optionalHeaderValueByType-0
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/extractHost.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/extractHost.rst
index c814c454f1..d234e78f6c 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/extractHost.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/extractHost.rst
@@ -23,5 +23,5 @@ to its inner route.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostExamplesSpec.scala
-   :snippet: extract-hostname
\ No newline at end of file
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
+   :snippet: extractHost
\ No newline at end of file
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/host.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/host.rst
index 270b308bab..6faf6355e4 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/host.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/host-directives/host.rst
@@ -36,23 +36,23 @@ Example
 
 Matching a list of hosts:
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
    :snippet: list-of-hosts
 
 Making sure the host satisfies the given predicate
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
    :snippet: predicate
 
 Using a regular expressions:
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
    :snippet: using-regex
 
 Beware that in the case of introducing multiple capturing groups in the regex such as in the case bellow, the
 directive will fail at runtime, at the moment the route tree is evaluated for the first time. This might cause
 your http handler actor to enter in a fail/restart loop depending on your supervision strategy.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/HostDirectivesExamplesSpec.scala
    :snippet: failing-regex
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/completeWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/completeWith.rst
index 9343aeac10..b5ee86a344 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/completeWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/completeWith.rst
@@ -32,15 +32,15 @@ The following example uses ``spray-json`` to marshall a simple ``Person`` class
 response.  It utilizes ``SprayJsonSupport`` via the ``PersonJsonSupport`` object as the in-scope
 unmarshaller.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-json-support 
 
-   ... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-case-class
 
 The ``findPerson`` takes an argument of type ``Person => Unit`` which is generated by the ``completeWith``
 call.  We can handle any logic we want in ``findPerson`` and call our completion function to
 complete the request.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: example-completeWith-with-json
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/entity.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/entity.rst
index 62af516e77..15ad2704c7 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/entity.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/entity.rst
@@ -40,13 +40,13 @@ Examples
 The following example uses ``spray-json`` to unmarshall a json request into a simple ``Person`` 
 class.  It utilizes ``SprayJsonSupport`` via the ``PersonJsonSupport`` object as the in-scope unmarshaller.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-case-class
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-json-support
 
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: example-entity-with-json
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/handleWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/handleWith.rst
index 7f7825cec1..d2a311fd2a 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/handleWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/marshalling-directives/handleWith.rst
@@ -36,13 +36,13 @@ Examples
 
 The following example uses an ``updatePerson`` function with a ``Person`` case class as an input and output.  We plug this function into our route using ``handleWith``.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-case-class
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: example-handleWith-with-json
 
 The PersonJsonSupport object handles both marshalling and unmarshalling of the Person case class.
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: person-json-support
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/delete.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/delete.rst
index 820343967f..00f69244e7 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/delete.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/delete.rst
@@ -24,5 +24,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: delete-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/get.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/get.rst
index c71fcba590..0da6fcf195 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/get.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/get.rst
@@ -23,5 +23,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: get-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/head.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/head.rst
index eec9e4f83c..18de2bbb3b 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/head.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/head.rst
@@ -26,5 +26,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: head-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/method.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/method.rst
index 7e20531c58..b21752bf37 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/method.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/method.rst
@@ -22,5 +22,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: method-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/options.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/options.rst
index 1bee7f153d..e35ef71493 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/options.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/options.rst
@@ -22,5 +22,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: options-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/patch.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/patch.rst
index ac3e3d21d1..e7abe883f1 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/patch.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/patch.rst
@@ -23,5 +23,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: patch-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/post.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/post.rst
index 5e4fca5de5..766f5d55c0 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/post.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/post.rst
@@ -23,5 +23,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: post-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/put.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/put.rst
index 4e30f7458c..b2522ec7a3 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/put.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/put.rst
@@ -22,5 +22,5 @@ by the default :ref:`RejectionHandler <The RejectionHandler>`.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MethodDirectivesExamplesSpec.scala
   :snippet: put-method
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/extractClientIP.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/extractClientIP.rst
index cf0ba704ea..3f6d3ec6a2 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/extractClientIP.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/extractClientIP.rst
@@ -21,6 +21,6 @@ setting ``akka.http.server.remote-address-header`` is set to ``on``. Per default
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
   :snippet: extractClientIP-example
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/rejectEmptyResponse.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/rejectEmptyResponse.rst
index 1774338769..30aeb74129 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/rejectEmptyResponse.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/rejectEmptyResponse.rst
@@ -22,5 +22,5 @@ usually marshalled to an empty but successful result. In many cases ``None`` sho
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
   :snippet: rejectEmptyResponse-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityEmpty.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityEmpty.rst
index f9e1528ec1..2e2e0c8791 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityEmpty.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityEmpty.rst
@@ -23,5 +23,5 @@ The opposite filter is available as ``requestEntityPresent``.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
   :snippet: requestEntityEmptyPresent-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityPresent.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityPresent.rst
index 78ae2b416e..6fe3426999 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityPresent.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/requestEntityPresent.rst
@@ -23,5 +23,5 @@ The opposite filter is available as ``requestEntityEmpty``.
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
   :snippet: requestEntityEmptyPresent-example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/validate.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/validate.rst
index 66aecd3e28..c3c1fa8c79 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/validate.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/misc-directives/validate.rst
@@ -16,5 +16,5 @@ Signature
 Example
 -------
 
-... includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MiscDirectivesExamplesSpec.scala
   :snippet: validate-example