From cddb1ade40e525a2e04ab0da6961e338de13767b Mon Sep 17 00:00:00 2001
From: Konrad Malawski <konrad.malawski@typesafe.com>
Date: Fri, 9 Oct 2015 15:19:36 +0200
Subject: [PATCH] =htc,doc #18496 make all directive docs have the same style,
 some additions

---
 .../directives/method-directives/index.rst          |  2 +-
 .../request-vals/form-field-request-vals.rst        |  7 ++++---
 .../java/http/routing-dsl/request-vals/index.rst    |  9 +++++++++
 .../http/routing-dsl/directives/alphabetically.rst  |  2 +-
 .../basic-directives/mapRouteResultWithPF.rst       |  2 +-
 .../basic-directives/recoverRejectionsWith.rst      |  8 ++++----
 .../directives/basic-directives/textract.rst        |  6 ++++--
 .../directives/basic-directives/tprovide.rst        |  4 +++-
 .../basic-directives/withExecutionContext.rst       |  2 --
 .../directives/basic-directives/withLog.rst         |  2 --
 .../basic-directives/withMaterializer.rst           |  2 --
 .../directives/basic-directives/withSettings.rst    |  2 --
 .../cache-condition-directives/conditional.rst      |  8 ++++----
 .../directives/cookie-directives/cookie.rst         |  5 ++---
 .../directives/cookie-directives/deleteCookie.rst   |  3 +--
 .../directives/cookie-directives/optionalCookie.rst |  3 +--
 .../directives/cookie-directives/setCookie.rst      |  3 +--
 .../directives/debugging-directives/logRequest.rst  |  2 --
 .../debugging-directives/logRequestResult.rst       |  8 ++++----
 .../directives/debugging-directives/logResult.rst   |  5 ++---
 .../execution-directives/handleExceptions.rst       |  3 +--
 .../getFromBrowseableDirectories.rst                |  3 ---
 .../getFromBrowseableDirectory.rst                  |  3 ---
 .../getFromDirectory.rst                            |  2 --
 .../file-and-resource-directives/getFromFile.rst    |  2 --
 .../getFromResource.rst                             |  4 +---
 .../getFromResourceDirectory.rst                    |  4 +---
 .../listDirectoryContents.rst                       |  8 +++-----
 .../directives/form-field-directives/formField.rst  |  7 ++-----
 .../directives/form-field-directives/formFields.rst |  3 +--
 .../future-directives/completeOrRecoverWith.rst     |  6 +-----
 .../directives/future-directives/onComplete.rst     |  9 +++------
 .../directives/future-directives/onSuccess.rst      |  9 +++------
 .../directives/header-directives/headerValue.rst    | 12 ++++++------
 .../header-directives/headerValueByName.rst         |  7 ++++---
 .../header-directives/headerValueByType.rst         | 10 +++++-----
 .../directives/header-directives/headerValuePF.rst  | 13 +++++++------
 .../header-directives/optionalHeaderValue.rst       |  7 +++----
 .../header-directives/optionalHeaderValueByName.rst |  5 ++---
 .../header-directives/optionalHeaderValueByType.rst |  5 ++---
 .../header-directives/optionalHeaderValuePF.rst     |  7 +++----
 .../directives/host-directives/extractHost.rst      |  6 +-----
 .../routing-dsl/directives/host-directives/host.rst |  5 +----
 .../rst/scala/http/routing-dsl/directives/index.rst |  2 +-
 .../marshalling-directives/completeWith.rst         |  5 ++---
 .../directives/marshalling-directives/entity.rst    |  9 ++++-----
 .../marshalling-directives/handleWith.rst           | 11 +++++------
 .../directives/method-directives/delete.rst         |  3 +--
 .../directives/method-directives/extractMethod.rst  |  3 ---
 .../directives/method-directives/get.rst            |  3 +--
 .../directives/method-directives/head.rst           |  3 +--
 .../directives/method-directives/method.rst         |  3 +--
 .../directives/method-directives/options.rst        |  3 +--
 .../overrideMethodWithParameter.rst                 |  3 +--
 .../directives/method-directives/patch.rst          |  3 +--
 .../directives/method-directives/post.rst           |  3 +--
 .../directives/method-directives/put.rst            |  3 +--
 .../directives/misc-directives/extractClientIP.rst  |  4 +---
 .../misc-directives/rejectEmptyResponse.rst         |  3 +--
 .../misc-directives/requestEntityEmpty.rst          |  9 ++++-----
 .../misc-directives/requestEntityPresent.rst        |  8 +++-----
 .../directives/misc-directives/validate.rst         |  3 +--
 .../directives/parameter-directives/parameter.rst   |  5 +----
 .../parameter-directives/parameterMap.rst           |  6 ++----
 .../parameter-directives/parameterMultiMap.rst      | 11 ++++++-----
 .../parameter-directives/parameterSeq.rst           |  8 +++-----
 .../directives/parameter-directives/parameters.rst  |  4 ++--
 .../routing-dsl/directives/path-directives/path.rst |  6 ++----
 .../directives/path-directives/pathEnd.rst          |  7 +++----
 .../path-directives/pathEndOrSingleSlash.rst        |  6 ++----
 .../directives/path-directives/pathPrefix.rst       |  6 ++----
 .../directives/path-directives/pathPrefixTest.rst   |  8 +++-----
 .../directives/path-directives/pathSingleSlash.rst  |  6 ++----
 .../directives/path-directives/pathSuffix.rst       |  6 ++----
 .../directives/path-directives/pathSuffixTest.rst   |  8 +++-----
 .../directives/path-directives/rawPathPrefix.rst    |  6 ++----
 .../path-directives/rawPathPrefixTest.rst           |  8 +++-----
 .../redirectToNoTrailingSlashIfPresent.rst          |  9 ++++-----
 .../redirectToTrailingSlashIfMissing.rst            |  9 ++++-----
 .../range-directives/withRangeSupport.rst           |  6 ++----
 .../respondWithDefaultHeader.rst                    | 10 ++++------
 .../respondWithDefaultHeaders.rst                   | 11 ++++++-----
 .../respond-with-directives/respondWithHeader.rst   |  6 ++----
 .../respond-with-directives/respondWithHeaders.rst  |  7 +++----
 .../directives/route-directives/complete.rst        |  5 ++---
 .../directives/route-directives/failWith.rst        |  6 ++----
 .../directives/route-directives/redirect.rst        |  4 +---
 .../directives/route-directives/reject.rst          |  4 +---
 .../directives/scheme-directives/extractScheme.rst  |  6 +-----
 .../directives/scheme-directives/scheme.rst         |  3 +--
 .../security-directives/authenticateBasic.rst       |  3 +--
 .../security-directives/authenticateBasicAsync.rst  |  5 ++---
 .../security-directives/authenticateBasicPF.rst     |  5 ++---
 .../authenticateBasicPFAsync.rst                    |  3 +--
 .../security-directives/authenticateOAuth2.rst      |  3 +--
 .../security-directives/authenticateOAuth2Async.rst |  3 +--
 .../security-directives/authenticateOAuth2PF.rst    |  3 +--
 ...th2AsyncPF.rst => authenticateOAuth2PFAsync.rst} |  8 ++++----
 .../authenticateOrRejectWithChallenge.rst           |  3 +--
 .../directives/security-directives/authorize.rst    |  3 +--
 .../security-directives/extractCredentials.rst      |  2 --
 .../handleWebsocketMessages.rst                     |  3 ---
 .../handleWebsocketMessagesForProtocol.rst          |  7 +++----
 103 files changed, 212 insertions(+), 335 deletions(-)
 rename akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/{authenticateOAuth2AsyncPF.rst => authenticateOAuth2PFAsync.rst} (89%)

diff --git a/akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/index.rst
index e5241a42f2..e63c3e900c 100644
--- a/akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/index.rst
+++ b/akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/index.rst
@@ -1,4 +1,4 @@
-.. _MethodDirectives:
+.. _method-directives-java:
 
 MethodDirectives
 ================
diff --git a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/form-field-request-vals.rst b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/form-field-request-vals.rst
index c72031a706..0834fe4c92 100644
--- a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/form-field-request-vals.rst
+++ b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/form-field-request-vals.rst
@@ -9,9 +9,10 @@ Description
 -----------
 ``FormField`` request values allow extracting fields submitted as ``application/x-www-form-urlencoded`` values or concrete instances from HTTP requests.
 
-The ``RequestVal`` builder is made up of 2 steps, initially you need to pick which Header to extract (``byName`` or
-``byClass``) and then you need to pick if the header is optionally available or required (i.e. the route should not
-match if the header is not present in the request). This is done using one of the below depicted methods::
+The ``FormField`` request value builder is made up of 2 steps, initially you need to pick which what type of value you
+want to extract from the field (for example ``intValue``, which would reject the route if the value is not an ``int``),
+and then **optionally** you may specify if the value is optional (by calling ``optional()`` on the ``RequestVal``)
+or has a default value (by calling ``withDefault()`` on the ``RequestVal``).
 
 Examples
 --------
diff --git a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst
index 2a7fb32428..1ba0178bb3 100644
--- a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst
+++ b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst
@@ -43,3 +43,12 @@ akka.http.javadsl.server.values.FormFieldsPathMatchers
   Contains request values to match and access URI path segments.
 akka.http.javadsl.server.values.FormFieldsCustomRequestVal
   An abstract class to implement arbitrary custom request values.
+
+See also
+--------
+
+.. toctree::
+  :maxdepth: 1
+
+  form-field-request-vals
+  header-request-vals
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst
index 36751e2587..dbedb4cfc7 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst
@@ -20,7 +20,7 @@ Directive                                   Description
                                             a given ``AsyncAuthenticator[T]``
 :ref:`-authenticateOAuth2PF-`               Wraps the inner route with OAuth Bearer Token authentication support using
                                             a given ``AuthenticatorPF[T]``
-:ref:`-authenticateOAuth2AsyncPF-`          Wraps the inner route with OAuth Bearer Token authentication support using
+:ref:`-authenticateOAuth2PFAsync-`          Wraps the inner route with OAuth Bearer Token authentication support using
                                             a given ``AsyncAuthenticatorPF[T]``
 :ref:`-authenticateOrRejectWithChallenge-`  Lifts an authenticator function into a directive
 :ref:`-authorize-`                          Applies the given authorization check to the request
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResultWithPF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResultWithPF.rst
index bbd7d7e298..47cdb6a60e 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResultWithPF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/mapRouteResultWithPF.rst
@@ -12,7 +12,7 @@ Signature
 Description
 -----------
 
-Asynchronous variant of :ref:`mapRouteResultPF`.
+Asynchronous variant of :ref:`-mapRouteResultPF-`.
 
 Changes the message the inner route sends to the responder.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst
index 9a4a79a4de..2e3eee0ece 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst
@@ -3,10 +3,6 @@
 recoverRejectionsWith
 =====================
 
-Transforms rejections from the inner route with an ``immutable.Seq[Rejection] ⇒ Future[RouteResult]`` function.
-
-Asynchronous version of :ref:`-recoverRejections-`.
-
 Signature
 ---------
 
@@ -19,6 +15,10 @@ Description
 **Low level directive** – unless you're sure you need to be working on this low-level you might instead
 want to try the :ref:`-handleRejections-` directive which provides a nicer DSL for building rejection handlers.
 
+Transforms rejections from the inner route with an ``immutable.Seq[Rejection] ⇒ Future[RouteResult]`` function.
+
+Asynchronous version of :ref:`-recoverRejections-`.
+
 See :ref:`-recoverRejections-` (the synchronous equivalent of this directive) for a detailed description.
 
 .. note::
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/textract.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/textract.rst
index 000e14f86e..a4ef8d37bc 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/textract.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/textract.rst
@@ -3,8 +3,6 @@
 textract
 ========
 
-Calculates a tuple of values from the request context and provides them to the inner route.
-
 Signature
 ---------
 
@@ -13,6 +11,8 @@ Signature
 
 Description
 -----------
+Extracts a tuple of values from the request context and provides them to the inner route.
+
 
 The ``textract`` directive is used as a building block for :ref:`Custom Directives` to extract data from the
 ``RequestContext`` and provide it to the inner route. To extract just one value use the :ref:`-extract-` directive. To
@@ -20,6 +20,8 @@ provide a constant value independent of the ``RequestContext`` use the :ref:`-tp
 
 See :ref:`ProvideDirectives` for an overview of similar directives.
 
+See also :ref:`-extract-` for extracting a single value.
+
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/tprovide.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/tprovide.rst
index 285c3b6de8..571a2de8cf 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/tprovide.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/tprovide.rst
@@ -3,7 +3,6 @@
 tprovide
 ========
 
-Provides a tuple of values to the inner route.
 
 Signature
 ---------
@@ -14,12 +13,15 @@ Signature
 Description
 -----------
 
+Provides a tuple of values to the inner route.
+
 The ``tprovide`` directive is used as a building block for :ref:`Custom Directives` to provide data to the inner route.
 To provide just one value use the :ref:`-provide-` directive. If you want to provide values calculated from the
 ``RequestContext`` use the :ref:`-textract-` directive instead.
 
 See :ref:`ProvideDirectives` for an overview of similar directives.
 
+See also :ref:`-provide-` for providing a single value.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withExecutionContext.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withExecutionContext.rst
index 4e6075a74e..db7e57c422 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withExecutionContext.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withExecutionContext.rst
@@ -3,8 +3,6 @@
 withExecutionContext
 ====================
 
-Runs its inner route with the given alternative :class:`ExecutionContext`.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withLog.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withLog.rst
index 654d28875e..7956e8c024 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withLog.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withLog.rst
@@ -3,8 +3,6 @@
 withLog
 =======
 
-Runs its inner route with the given alternative :class:`LoggingAdapter`.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withMaterializer.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withMaterializer.rst
index 7f03560f10..a6c2995286 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withMaterializer.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withMaterializer.rst
@@ -3,8 +3,6 @@
 withMaterializer
 ================
 
-Runs its inner route with the given alternative ``Materializer``.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withSettings.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withSettings.rst
index e129f59c5d..148589815c 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withSettings.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/withSettings.rst
@@ -3,8 +3,6 @@
 withSettings
 ============
 
-Runs its inner route with the given alternative :class:`RoutingSettings`.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cache-condition-directives/conditional.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cache-condition-directives/conditional.rst
index 65b582c9f3..c456854f84 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cache-condition-directives/conditional.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cache-condition-directives/conditional.rst
@@ -3,10 +3,6 @@
 conditional
 ===========
 
-Wraps its inner route with support for Conditional Requests as defined
-by http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26.
-
-
 Signature
 ---------
 
@@ -17,6 +13,10 @@ Signature
 Description
 -----------
 
+Wraps its inner route with support for Conditional Requests as defined
+by http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26.
+
+
 Depending on the given ``eTag`` and ``lastModified`` values this directive immediately responds with
 ``304 Not Modified`` or ``412 Precondition Failed`` (without calling its inner route) if the request comes with the
 respective conditional headers. Otherwise the request is simply passed on to its inner route.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/cookie.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/cookie.rst
index ceb6de5fcb..f75dcab233 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/cookie.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/cookie.rst
@@ -3,9 +3,6 @@
 cookie
 ======
 
-Extracts a cookie with a given name from a request or otherwise rejects the request with a ``MissingCookieRejection`` if
-the cookie is missing.
-
 Signature
 ---------
 
@@ -14,6 +11,8 @@ Signature
 
 Description
 -----------
+Extracts a cookie with a given name from a request or otherwise rejects the request with a ``MissingCookieRejection`` if
+the cookie is missing.
 
 Use the :ref:`-optionalCookie-` directive instead if you want to support missing cookies in your inner route.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/deleteCookie.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/deleteCookie.rst
index fe43aba81d..3414abbf1a 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/deleteCookie.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/deleteCookie.rst
@@ -3,8 +3,6 @@
 deleteCookie
 ============
 
-Adds a header to the response to request the removal of the cookie with the given name on the client.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Adds a header to the response to request the removal of the cookie with the given name on the client.
 
 Use the :ref:`-setCookie-` directive to update a cookie.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/optionalCookie.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/optionalCookie.rst
index 6b10c6044a..b880fa53a0 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/optionalCookie.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/optionalCookie.rst
@@ -3,8 +3,6 @@
 optionalCookie
 ==============
 
-Extracts an optional cookie with a given name from a request.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Extracts an optional cookie with a given name from a request.
 
 Use the :ref:`-cookie-` directive instead if the inner route does not handle a missing cookie.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/setCookie.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/setCookie.rst
index 5647327159..0651e64e74 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/setCookie.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/cookie-directives/setCookie.rst
@@ -3,8 +3,6 @@
 setCookie
 =========
 
-Adds a header to the response to request the update of the cookie with the given name on the client.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Adds a header to the response to request the update of the cookie with the given name on the client.
 
 Use the :ref:`-deleteCookie-` directive to delete a cookie.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequest.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequest.rst
index 367f1755c1..2cab1bd701 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequest.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequest.rst
@@ -3,8 +3,6 @@
 logRequest
 ==========
 
-Logs the request.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst
index ed5f6945b6..801bd8fc65 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst
@@ -3,8 +3,6 @@
 logRequestResult
 ================
 
-Logs request and response.
-
 Signature
 ---------
 
@@ -23,9 +21,11 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 
 Description
 -----------
+Logs both, the request and the response.
 
-This directive is a combination of ``logRequest`` and ``logResult``. See ``logRequest`` for the general description
-how these directives work.
+This directive is a combination of :ref:`-logRequest-` and :ref:`-logResult-`.
+
+See :ref:`-logRequest-` for the general description how these directives work.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logResult.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logResult.rst
index ccb9eb2d68..bdbbe4e2de 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logResult.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/debugging-directives/logResult.rst
@@ -3,8 +3,6 @@
 logResult
 =========
 
-Logs the response.
-
 Signature
 ---------
 
@@ -23,8 +21,9 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 
 Description
 -----------
+Logs the response.
 
-See ``logRequest`` for the general description how these directives work. This directive is different
+See :ref:`-logRequest-` for the general description how these directives work. This directive is different
 as it requires a ``LoggingMagnet[Any => Unit]``. Instead of just logging ``HttpResponses``, ``logResult`` is able to
 log any :ref:`RouteResult` coming back from the inner route.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/execution-directives/handleExceptions.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/execution-directives/handleExceptions.rst
index 375f89e1bd..9735e77277 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/execution-directives/handleExceptions.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/execution-directives/handleExceptions.rst
@@ -3,8 +3,6 @@
 handleExceptions
 ================
 
-Catches exceptions thrown by the inner route and handles them using the specified ``ExceptionHandler``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Catches exceptions thrown by the inner route and handles them using the specified ``ExceptionHandler``.
 
 Using this directive is an alternative to using a global implicitly defined ``ExceptionHandler`` that
 applies to the complete route.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst
index bfa18445ed..245d7adf0d 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst
@@ -3,9 +3,6 @@
 getFromBrowseableDirectories
 ============================
 
-Serves the content of the given directories as a file system browser,
-i.e. files are sent and directories served as *browsable* listings.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst
index ef0ce61900..126860f912 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst
@@ -3,9 +3,6 @@
 getFromBrowseableDirectory
 ==========================
 
-Serves the content of the given directory as a file system browser,
-i.e. files are sent and directories served as *browsable* listings.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst
index ba1c9b6d46..dac8ea1816 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst
@@ -3,8 +3,6 @@
 getFromDirectory
 ================
 
-Completes GET requests with the content of a file underneath the given directory.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst
index 6b22a1d1ea..a0c43b4d51 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst
@@ -3,8 +3,6 @@
 getFromFile
 ===========
 
-Completes GET requests with the content of the given file.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst
index aa42760924..559ac9c962 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst
@@ -3,8 +3,6 @@
 getFromResource
 ===============
 
-Completes GET requests with the content of the given classpath resource.
-
 Signature
 ---------
 
@@ -16,7 +14,7 @@ Description
 
 Completes GET requests with the content of the given classpath resource.
 
-For details refer to :ref:`getFromFile` which works the same way but obtaining the file from the filesystem
+For details refer to :ref:`-getFromFile-` which works the same way but obtaining the file from the filesystem
 instead of the applications classpath.
 
 Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst
index 9d798a51f2..0780b5c2be 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst
@@ -3,8 +3,6 @@
 getFromResourceDirectory
 ========================
 
-Completes GET requests with the content of the given classpath resource directory.
-
 Signature
 ---------
 
@@ -16,7 +14,7 @@ Description
 
 Completes GET requests with the content of the given classpath resource directory.
 
-For details refer to :ref:`getFromDirectory` which works the same way but obtaining the file from the filesystem
+For details refer to :ref:`-getFromDirectory-` which works the same way but obtaining the file from the filesystem
 instead of the applications classpath.
 
 Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst
index d0c4e95807..4104a88652 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst
@@ -3,9 +3,6 @@
 listDirectoryContents
 =====================
 
-Completes GET requests with a unified listing of the contents of all given directories. The actual rendering of the
-directory contents is performed by the in-scope `Marshaller[DirectoryListing]`.
-
 Signature
 ---------
 
@@ -15,11 +12,12 @@ Signature
 Description
 -----------
 
-The ``listDirectoryContents`` directive renders a response only for directories.
+Completes GET requests with a unified listing of the contents of all given directories. The actual rendering of the
+directory contents is performed by the in-scope ``Marshaller[DirectoryListing]``.
 
 To just serve files use :ref:`-getFromDirectory-`.
 
-To serve files and provide a browseable directory listing use :ref:`-getFromBrowsableDirectories-` instead.
+To serve files and provide a browseable directory listing use :ref:`-getFromBrowseableDirectories-` instead.
 
 The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``, you can read more about it in
 :ref:`-getFromDirectory-` 's documentation.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formField.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formField.rst
index 1aa9a32dd1..37c99c283e 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formField.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/form-field-directives/formField.rst
@@ -3,10 +3,6 @@
 formField
 =========
 
-Allows extracting a single Form field sent in the request.
-
-An alias for :ref:`-formFields-`.
-
 Signature
 ---------
 
@@ -15,8 +11,9 @@ Signature
 
 Description
 -----------
+Allows extracting a single Form field sent in the request.
 
-See :ref:`-formFields-`.
+See :ref:`-formFields-` for an in-depth description.
 
 Example
 -------
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 bd6d8bb049..abb95e05de 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
@@ -3,8 +3,6 @@
 formFields
 ==========
 
-Extracts fields from POST requests generated by HTML forms.
-
 Signature
 ---------
 
@@ -22,6 +20,7 @@ The signature shown is simplified and written in pseudo-syntax, the real signatu
 
 Description
 -----------
+Extracts fields from POST requests generated by HTML forms.
 
 Form fields can be either extracted as a String or can be converted to another type. The parameter name
 can be supplied either as a String or as a Symbol. Form field extraction can be modified to mark a field
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 d0ae968629..b616abff09 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,9 +3,6 @@
 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,8 +11,7 @@ Signature
 
 Description
 -----------
-
-If the future succeeds the request is completed using the value's marshaller (this directive therefore
+If the ``Future[T]`` 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``.
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 dcddf9a285..64b7625e66 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,9 +3,6 @@
 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,11 +11,11 @@ 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]``.
+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.
 
 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
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 1825fa6511..2658782346 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,9 +3,6 @@
 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 +11,10 @@ Signature
 
 Description
 -----------
+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.
 
-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``.
+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.
 
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 f25a5ed69a..c245cfd8c2 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
@@ -3,9 +3,6 @@
 headerValue
 ===========
 
-Traverses the list of request headers with the specified function and extracts the first value the function returns as
-``Some(value)``.
-
 Signature
 ---------
 
@@ -14,14 +11,17 @@ Signature
 
 Description
 -----------
+Traverses the list of request headers with the specified function and extracts the first value the function returns as
+``Some(value)``.
 
-The ``headerValue`` directive is a mixture of ``map`` and ``find`` on the list of request headers. The specified function
+The :ref:`-headerValue-` directive is a mixture of ``map`` and ``find`` on the list of request headers. The specified function
 is called once for each header until the function returns ``Some(value)``. This value is extracted and presented to the
 inner route. If the function throws an exception the request is rejected with a ``MalformedHeaderRejection``. If the
 function returns ``None`` for every header the request is rejected as "NotFound".
 
-This directive is the basis for building other request header related directives. See ``headerValuePF`` for a nicer
-syntactic alternative.
+This directive is the basis for building other request header related directives.
+
+See also :ref:`-headerValuePF-` for a nicer syntactic alternative.
 
 Example
 -------
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 2e962686d4..55f322c772 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
@@ -3,8 +3,6 @@
 headerValueByName
 =================
 
-Extracts the value of the HTTP request header with the given name.
-
 Signature
 ---------
 
@@ -13,9 +11,12 @@ Signature
 
 Description
 -----------
+Extracts the value of the HTTP request header with the given name.
 
 The name can be given as a ``String`` or as a ``Symbol``. If no header with a matching name is found the request
-is rejected with a ``MissingHeaderRejection``. If the header is expected to be missing in some cases or to customize
+is rejected with a ``MissingHeaderRejection``.
+
+If the header is expected to be missing in some cases or to customize
 handling when the header is missing use the :ref:`-optionalHeaderValueByName-` directive instead.
 
 Example
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 e936eda4a9..96d560a214 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
@@ -3,8 +3,6 @@
 headerValueByType
 =================
 
-Traverses the list of request headers and extracts the first header of the given type.
-
 Signature
 ---------
 
@@ -19,11 +17,13 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 
 Description
 -----------
+Traverses the list of request headers and extracts the first header of the given type.
 
 The ``headerValueByType`` directive finds a header of the given type in the list of request header. If no header of
-the given type is found the request is rejected with a ``MissingHeaderRejection``. If the header is expected to be
-missing in some cases or to customize handling when the header is missing use the ``optionalHeaderValueByType``
-directive instead.
+the given type is found the request is rejected with a ``MissingHeaderRejection``.
+
+If the header is expected to be missing in some cases or to customize handling when the header
+is missing use the :ref:`-optionalHeaderValueByType-` directive instead.
 
 Example
 -------
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 16fa95590f..7b3085f423 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
@@ -3,9 +3,6 @@
 headerValuePF
 =============
 
-Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
-result of calling the function.
-
 Signature
 ---------
 
@@ -14,10 +11,14 @@ Signature
 
 Description
 -----------
+Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
+result of calling the function.
 
-The ``headerValuePF`` directive is an alternative syntax version of ``headerValue``.  If the function throws an
-exception the request is rejected with a ``MalformedHeaderRejection``. If the function is not defined for
-any header the request is rejected as "NotFound".
+The ``headerValuePF`` directive is an alternative syntax version of :ref:`-headerValue-`.
+
+If the function throws an exception the request is rejected with a ``MalformedHeaderRejection``.
+
+If the function is not defined for any header the request is rejected as "NotFound".
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst
index 0b52870506..cf9aa299c7 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst
@@ -3,9 +3,6 @@
 optionalHeaderValue
 ===================
 
-Traverses the list of request headers with the specified function and extracts the first value the function returns as
-``Some(value)``.
-
 Signature
 ---------
 
@@ -14,8 +11,10 @@ Signature
 
 Description
 -----------
+Traverses the list of request headers with the specified function and extracts the first value the function returns as
+``Some(value)``.
 
-The ``optionalHeaderValue`` directive is similar to the ``headerValue`` directive but always extracts an ``Option``
+The ``optionalHeaderValue`` directive is similar to the :ref:`-headerValue-` directive but always extracts an ``Option``
 value instead of rejecting the request if no matching header could be found.
 
 Example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst
index fe894520e7..cf51fb5d6e 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst
@@ -3,8 +3,6 @@
 optionalHeaderValueByName
 =========================
 
-Optionally extracts the value of the HTTP request header with the given name.
-
 Signature
 ---------
 
@@ -13,8 +11,9 @@ Signature
 
 Description
 -----------
+Optionally extracts the value of the HTTP request header with the given name.
 
-The ``optionalHeaderValueByName`` directive is similar to the ``headerValueByName`` directive but always extracts
+The ``optionalHeaderValueByName`` directive is similar to the :ref:`-headerValueByName-` directive but always extracts
 an ``Option`` value instead of rejecting the request if no matching header could be found.
 
 Example
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 1bf3cea2de..a54fa51956 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
@@ -3,8 +3,6 @@
 optionalHeaderValueByType
 =========================
 
-Optionally extracts the value of the HTTP request header of the given type.
-
 Signature
 ---------
 
@@ -19,8 +17,9 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 
 Description
 -----------
+Optionally extracts the value of the HTTP request header of the given type.
 
-The ``optionalHeaderValueByType`` directive is similar to the ``headerValueByType`` directive but always extracts
+The ``optionalHeaderValueByType`` directive is similar to the :ref:`-headerValueByType-` directive but always extracts
 an ``Option`` value instead of rejecting the request if no matching header could be found.
 
 Example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst
index c81985f72f..728b9131ad 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst
@@ -3,9 +3,6 @@
 optionalHeaderValuePF
 =====================
 
-Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
-result of calling the function.
-
 Signature
 ---------
 
@@ -14,8 +11,10 @@ Signature
 
 Description
 -----------
+Calls the specified partial function with the first request header the function is ``isDefinedAt`` and extracts the
+result of calling the function.
 
-The ``optionalHeaderValuePF`` directive is similar to the ``headerValuePF`` directive but always extracts an ``Option``
+The ``optionalHeaderValuePF`` directive is similar to the :ref:`-headerValuePF-` directive but always extracts an ``Option``
 value instead of rejecting the request if no matching header could be found.
 
 Example
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 185bdd953b..3240db8a4c 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
@@ -3,9 +3,6 @@
 extractHost
 ===========
 
-Extracts the hostname part of the Host header value in the request.
-
-
 Signature
 ---------
 
@@ -16,8 +13,7 @@ Signature
 Description
 -----------
 
-Extract the hostname part of the ``Host`` request header and expose it as a ``String`` extraction
-to its inner route.
+Extract the hostname part of the ``Host`` request header and expose it as a ``String`` extraction to its inner route.
 
 
 Example
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 0b2d3b86f0..4248c1e4b4 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
@@ -3,10 +3,6 @@
 host
 ====
 
-Filter requests matching conditions against the hostname part of the Host header value
-in the request.
-
-
 Signature
 ---------
 
@@ -16,6 +12,7 @@ Signature
 
 Description
 -----------
+Filter requests matching conditions against the hostname part of the Host header value in the request.
 
 The ``def host(hostNames: String*)`` overload rejects all requests with a hostname different from the given ones.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/index.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/index.rst
index 19cb5815ec..5c434fc5b5 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/index.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/index.rst
@@ -1,4 +1,4 @@
-.. _Directives:
+.. _directives:
 
 Directives
 ==========
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 6896d83abc..89db94fec7 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
@@ -3,9 +3,6 @@
 completeWith
 ============
 
-Uses the marshaller for a given type to produce a completion function that is passed to its 
-inner route.  You can use it to decouple marshaller resolution from request completion.  
-
 Signature
 ---------
 
@@ -14,6 +11,8 @@ Signature
 
 Description
 -----------
+Uses the marshaller for a given type to produce a completion function that is passed to its
+inner route.  You can use it to decouple marshaller resolution from request completion.
 
 The ``completeWith`` directive works in conjuction with ``instanceOf`` and ``spray.httpx.marshalling``
 to convert higher-level (object) structure into some lower-level serialized "wire format".
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 d95b73b6d8..b2de96c76a 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
@@ -3,11 +3,6 @@
 entity
 ======
 
-Unmarshalls the request entity to the given type and passes it to its inner Route.  An unmarshaller
-returns an ``Either`` with ``Right(value)`` if successful or ``Left(exception)`` for a failure.
-The ``entity`` method will either pass the ``value`` to the inner route or map the ``exception`` to a
-``akka.http.scaladsl.server.Rejection``.
-
 Signature
 ---------
 
@@ -16,6 +11,10 @@ Signature
 
 Description
 -----------
+Unmarshalls the request entity to the given type and passes it to its inner Route.  An unmarshaller
+returns an ``Either`` with ``Right(value)`` if successful or ``Left(exception)`` for a failure.
+The ``entity`` method will either pass the ``value`` to the inner route or map the ``exception`` to a
+``akka.http.scaladsl.server.Rejection``.
 
 The ``entity`` directive works in conjuction with ``as`` and ``akka.http.scaladsl.unmarshalling`` to
 convert some serialized "wire format" value into a higher-level object structure.  
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 e4c7bdb487..d06688332e 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
@@ -3,11 +3,6 @@
 handleWith
 ==========
 
-Completes the request using the given function. The input to the function is produced with 
-the in-scope entity unmarshaller and the result value of the function is marshalled with 
-the in-scope marshaller.  ``handleWith`` can be a convenient method combining ``entity`` with
-``complete``.
-
 Signature
 ---------
 
@@ -16,8 +11,12 @@ Signature
 
 Description
 -----------
+Completes the request using the given function. The input to the function is produced with
+the in-scope entity unmarshaller and the result value of the function is marshalled with
+the in-scope marshaller.  ``handleWith`` can be a convenient method combining ``entity`` with
+``complete``.
 
-The ``handleWith`` directive is used when you want to handle a route with a given function of 
+The ``handleWith`` directive is used when you want to handle a route with a given function of
 type A ⇒ B.  ``handleWith`` will use both an in-scope unmarshaller to convert a request into 
 type A and an in-scope marshaller to convert type B into a response. This is helpful when your 
 core business logic resides in some other class or you want your business logic to be independent
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 d3aba4aeec..1d182b9c0c 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
@@ -3,8 +3,6 @@
 delete
 ======
 
-Matches requests with HTTP method ``DELETE``.
-
 Signature
 ---------
 
@@ -14,6 +12,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``DELETE``.
 
 This directive filters an incoming request by its HTTP method. Only requests with
 method ``DELETE`` are passed on to the inner route. All others are rejected with a
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/extractMethod.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/extractMethod.rst
index 506ea253b7..e0ff7743ff 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/extractMethod.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/extractMethod.rst
@@ -3,8 +3,6 @@
 extractMethod
 =============
 
-Extracts the :class:`HttpMethod` from the request context which can be used programatically in a route.
-
 Signature
 ---------
 
@@ -13,7 +11,6 @@ Signature
 
 Description
 -----------
-
 Extracts the :class:`HttpMethod` from the request context and provides it for use for other directives explicitly.
 
 Example
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 1a24e9f8ef..d336db8e99 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
@@ -3,8 +3,6 @@
 get
 ===
 
-Matches requests with HTTP method ``GET``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``GET``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``GET`` are passed on to the inner route. All others are rejected with a
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 3d0414af3f..039258fc80 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
@@ -3,8 +3,6 @@
 head
 ====
 
-Matches requests with HTTP method ``HEAD``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``HEAD``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``HEAD`` are passed on to the inner route. All others are rejected with a
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 a21d8903ac..ad43393cda 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
@@ -3,8 +3,6 @@
 method
 ======
 
-Matches HTTP requests based on their method.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches HTTP requests based on their method.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 the specified method are passed on to the inner route. All others are rejected with a
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 63b206d2dc..f3f0fabca9 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
@@ -3,8 +3,6 @@
 options
 =======
 
-Matches requests with HTTP method ``OPTIONS``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``OPTIONS``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``OPTIONS`` are passed on to the inner route. All others are rejected with a
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/overrideMethodWithParameter.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/overrideMethodWithParameter.rst
index 19f01ea5c5..2affb57809 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/overrideMethodWithParameter.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/method-directives/overrideMethodWithParameter.rst
@@ -3,8 +3,6 @@
 overrideMethodWithParameter
 ===========================
 
-Changes the request method to the value of the specified query parameter.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Changes the request method to the value of the specified query parameter.
 
 Changes the HTTP method of the request to the value of the specified query string parameter.
 If the query string parameter is not specified this directive has no effect.
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 f6f5bd824c..224b3e04e0 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
@@ -3,8 +3,6 @@
 patch
 =====
 
-Matches requests with HTTP method ``PATCH``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``PATCH``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``PATCH`` are passed on to the inner route. All others are rejected with a
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 047f0f3bd1..2e4901cfcd 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
@@ -3,8 +3,6 @@
 post
 ====
 
-Matches requests with HTTP method ``POST``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``POST``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``POST`` are passed on to the inner route. All others are rejected with a
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 f40dec10e7..b824a3828d 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
@@ -3,8 +3,6 @@
 put
 ===
 
-Matches requests with HTTP method ``PUT``.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Matches requests with HTTP method ``PUT``.
 
 This directive filters the incoming request by its HTTP method. Only requests with
 method ``PUT`` are passed on to the inner route. All others are rejected with a
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 d8e2db32a2..02343bbf92 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
@@ -3,9 +3,6 @@
 extractClientIP
 ===============
 
-Provides the value of ``X-Forwarded-For``, ``Remote-Address``, or ``X-Real-IP`` headers as an instance of
-``HttpIp``.
-
 Signature
 ---------
 
@@ -14,6 +11,7 @@ Signature
 
 Description
 -----------
+Provides the value of ``X-Forwarded-For``, ``Remote-Address``, or ``X-Real-IP`` headers as an instance of ``HttpIp``.
 
 The akka-http server engine adds the ``Remote-Address`` header to every request automatically if the respective
 setting ``akka.http.server.remote-address-header`` is set to ``on``. Per default it is set to ``off``.
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 b9589e7393..dd2f684a74 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
@@ -3,8 +3,6 @@
 rejectEmptyResponse
 ===================
 
-Replaces a response with no content with an empty rejection.
-
 Signature
 ---------
 
@@ -14,6 +12,7 @@ Signature
 
 Description
 -----------
+Replaces a response with no content with an empty rejection.
 
 The ``rejectEmptyResponse`` directive is mostly used with marshalling ``Option[T]`` instances. The value ``None`` is
 usually marshalled to an empty but successful result. In many cases ``None`` should instead be handled as
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 1faf57fa43..5684a71c76 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
@@ -3,10 +3,6 @@
 requestEntityEmpty
 ==================
 
-A filter that checks if the request entity is empty and only then passes processing to the inner route.
-Otherwise, the request is rejected.
-
-
 Signature
 ---------
 
@@ -16,8 +12,11 @@ Signature
 
 Description
 -----------
+A filter that checks if the request entity is empty and only then passes processing to the inner route.
+Otherwise, the request is rejected.
 
-The opposite filter is available as ``requestEntityPresent``.
+
+See also :ref:`-requestEntityPresent-` for the opposite effect.
 
 
 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 d2b705fb5c..6e16da12da 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
@@ -3,10 +3,6 @@
 requestEntityPresent
 ====================
 
-A simple filter that checks if the request entity is present and only then passes processing to the inner route.
-Otherwise, the request is rejected.
-
-
 Signature
 ---------
 
@@ -16,8 +12,10 @@ Signature
 
 Description
 -----------
+A simple filter that checks if the request entity is present and only then passes processing to the inner route.
+Otherwise, the request is rejected.
 
-The opposite filter is available as ``requestEntityEmpty``.
+See also :ref:`-requestEntityEmpty-` for the opposite effect.
 
 
 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 ad671bb9e1..8782881255 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
@@ -3,8 +3,6 @@
 validate
 ========
 
-Allows validating a precondition before handling a route.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Allows validating a precondition before handling a route.
 
 Checks an arbitrary condition and passes control to the inner route if it returns ``true``.
 Otherwise, rejects the request with a ``ValidationRejection`` containing the given error message.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameter.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameter.rst
index 68a10e824b..9bead83e95 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameter.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameter.rst
@@ -3,10 +3,6 @@
 parameter
 =========
 
-Extracts a *query* parameter value from the request.
-
-An alias for :ref:`-parameters-`.
-
 Signature
 ---------
 
@@ -15,6 +11,7 @@ Signature
 
 Description
 -----------
+Extracts a *query* parameter value from the request.
 
 See :ref:`-parameters-` for a detailed description of this directive.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMap.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMap.rst
index fe842aabcc..531d6f2e77 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMap.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMap.rst
@@ -3,9 +3,6 @@
 parameterMap
 ============
 
-Extracts all parameters at once as a ``Map[String, String]`` mapping parameter names to
-parameter values.
-
 Signature
 ---------
 
@@ -14,10 +11,11 @@ Signature
 
 Description
 -----------
+Extracts all parameters at once as a ``Map[String, String]`` mapping parameter names to parameter values.
 
 If a query contains a parameter value several times, the map will contain the last one.
 
-See :ref:`which-parameter-directive` to understand when to use which directive.
+See also :ref:`which-parameter-directive` to understand when to use which directive.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMultiMap.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMultiMap.rst
index b92299d9fe..163d033975 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMultiMap.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterMultiMap.rst
@@ -3,9 +3,6 @@
 parameterMultiMap
 =================
 
-Extracts all parameters at once as a multi-map of type ``Map[String, List[String]`` mapping
-a parameter name to a list of all its values.
-
 Signature
 ---------
 
@@ -15,8 +12,12 @@ Signature
 Description
 -----------
 
-This directive can be used if parameters can occur several times. The order of values is
-not specified.
+Extracts all parameters at once as a multi-map of type ``Map[String, List[String]`` mapping
+a parameter name to a list of all its values.
+
+This directive can be used if parameters can occur several times.
+
+The order of values is *not* specified.
 
 See :ref:`which-parameter-directive` to understand when to use which directive.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterSeq.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterSeq.rst
index 1416154728..fbcf145369 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterSeq.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameterSeq.rst
@@ -3,8 +3,6 @@
 parameterSeq
 ============
 
-Extracts all parameters at once in the original order as (name, value) tuples of type ``(String, String)``.
-
 Signature
 ---------
 
@@ -13,11 +11,11 @@ Signature
 
 Description
 -----------
+Extracts all parameters at once in the original order as (name, value) tuples of type ``(String, String)``.
 
-This directive can be used if the exact order of parameters is important or if parameters can
-occur several times.
+This directive can be used if the exact order of parameters is important or if parameters can occur several times.
 
-See :ref:`which-parameter-directive` for other choices.
+See :ref:`which-parameter-directive` to understand when to use which directive.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameters.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameters.rst
index 2a271693c6..771e5394b5 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameters.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/parameter-directives/parameters.rst
@@ -3,8 +3,6 @@
 parameters
 ==========
 
-The parameters directive filters on the existence of several query parameters and extract their values.
-
 Signature
 ---------
 
@@ -22,6 +20,8 @@ The signature shown is simplified and written in pseudo-syntax, the real signatu
 
 Description
 -----------
+The parameters directive filters on the existence of several query parameters and extract their values.
+
 Query parameters can be either extracted as a String or can be converted to another type. The parameter name
 can be supplied either as a String or as a Symbol. Parameter extraction can be modified to mark a query parameter
 as required, optional, or repeated, or to filter requests where a parameter has a certain value:
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/path.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/path.rst
index ee32066289..5507c24199 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/path.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/path.rst
@@ -3,10 +3,6 @@
 path
 ====
 
-Matches the complete unmatched path of the ``RequestContext`` against the given ``PathMatcher``, potentially extracts
-one or more values (depending on the type of the argument).
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Matches the complete unmatched path of the ``RequestContext`` against the given ``PathMatcher``, potentially extracts
+one or more values (depending on the type of the argument).
 
 This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other
 potentially existing :ref:`-pathPrefix-` directives on higher levels of the routing structure.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEnd.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEnd.rst
index 46cd3c9204..df70df9073 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEnd.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEnd.rst
@@ -3,10 +3,6 @@
 pathEnd
 =======
 
-Only passes the request to its inner route if the unmatched path of the ``RequestContext`` is empty, i.e. the request
-path has been fully matched by a higher-level :ref:`-path-` or :ref:`-pathPrefix-` directive.
-
-
 Signature
 ---------
 
@@ -16,6 +12,9 @@ Signature
 
 Description
 -----------
+Only passes the request to its inner route if the unmatched path of the ``RequestContext`` is empty, i.e. the request
+path has been fully matched by a higher-level :ref:`-path-` or :ref:`-pathPrefix-` directive.
+
 
 This directive is a simple alias for ``rawPathPrefix(PathEnd)`` and is mostly used on an
 inner-level to discriminate "path already fully matched" from other alternatives (see the example below).
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEndOrSingleSlash.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEndOrSingleSlash.rst
index ae5fefcc7e..6fd330089d 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEndOrSingleSlash.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathEndOrSingleSlash.rst
@@ -3,10 +3,6 @@
 pathEndOrSingleSlash
 ====================
 
-Only passes the request to its inner route if the unmatched path of the ``RequestContext`` is either empty
-or contains only one single slash.
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Only passes the request to its inner route if the unmatched path of the ``RequestContext`` is either empty
+or contains only one single slash.
 
 This directive is a simple alias for ``rawPathPrefix(Slash.? ~ PathEnd)`` and is mostly used on an inner-level to
 discriminate "path already fully matched" from other alternatives (see the example below).
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefix.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefix.rst
index aa466d6fe2..b17476dd75 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefix.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefix.rst
@@ -3,10 +3,6 @@
 pathPrefix
 ==========
 
-Matches and consumes a prefix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
-potentially extracts one or more values (depending on the type of the argument).
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Matches and consumes a prefix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
+potentially extracts one or more values (depending on the type of the argument).
 
 This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other
 potentially existing ``pathPrefix`` or :ref:`-rawPathPrefix-` directives on higher levels of the routing structure.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefixTest.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefixTest.rst
index b880efdebc..c29db430b2 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefixTest.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathPrefixTest.rst
@@ -3,11 +3,6 @@
 pathPrefixTest
 ==============
 
-Checks whether the unmatched path of the ``RequestContext`` has a prefix matched by the given ``PathMatcher``.
-Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
-the unmatched path.
-
-
 Signature
 ---------
 
@@ -17,6 +12,9 @@ Signature
 
 Description
 -----------
+Checks whether the unmatched path of the ``RequestContext`` has a prefix matched by the given ``PathMatcher``.
+Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
+the unmatched path.
 
 This directive is very similar to the :ref:`-pathPrefix-` directive with the one difference that the path prefix
 it matched (if it matched) is *not* consumed. The unmatched path of the ``RequestContext`` is therefore left as
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSingleSlash.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSingleSlash.rst
index abbf6f60e9..21cf47b7bd 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSingleSlash.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSingleSlash.rst
@@ -3,10 +3,6 @@
 pathSingleSlash
 ===============
 
-Only passes the request to its inner route if the unmatched path of the ``RequestContext``
-contains exactly one single slash.
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Only passes the request to its inner route if the unmatched path of the ``RequestContext``
+contains exactly one single slash.
 
 This directive is a simple alias for ``pathPrefix(PathEnd)`` and is mostly used for matching requests to the root URI
 (``/``) on an inner-level to discriminate "all path segments matched" from other alternatives (see the example below).
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffix.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffix.rst
index ccd6f42cc7..2179e99d29 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffix.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffix.rst
@@ -3,10 +3,6 @@
 pathSuffix
 ==========
 
-Matches and consumes a suffix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
-potentially extracts one or more values (depending on the type of the argument).
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Matches and consumes a suffix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
+potentially extracts one or more values (depending on the type of the argument).
 
 This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other
 potentially existing path matching directives on higher levels of the routing structure.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffixTest.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffixTest.rst
index 1d78c458cd..e6c9b91137 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffixTest.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/pathSuffixTest.rst
@@ -3,11 +3,6 @@
 pathSuffixTest
 ==============
 
-Checks whether the unmatched path of the ``RequestContext`` has a suffix matched by the given ``PathMatcher``.
-Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
-the unmatched path.
-
-
 Signature
 ---------
 
@@ -17,6 +12,9 @@ Signature
 
 Description
 -----------
+Checks whether the unmatched path of the ``RequestContext`` has a suffix matched by the given ``PathMatcher``.
+Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
+the unmatched path.
 
 This directive is very similar to the :ref:`-pathSuffix-` directive with the one difference that the path suffix
 it matched (if it matched) is *not* consumed. The unmatched path of the ``RequestContext`` is therefore left as
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefix.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefix.rst
index 36a81c606e..0b81ec382a 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefix.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefix.rst
@@ -3,10 +3,6 @@
 rawPathPrefix
 =============
 
-Matches and consumes a prefix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
-potentially extracts one or more values (depending on the type of the argument).
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Matches and consumes a prefix of the unmatched path of the ``RequestContext`` against the given ``PathMatcher``,
+potentially extracts one or more values (depending on the type of the argument).
 
 This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other
 potentially existing ``rawPathPrefix`` or :ref:`-pathPrefix-` directives on higher levels of the routing structure.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefixTest.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefixTest.rst
index 7d895e32dd..8886437bc0 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefixTest.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/rawPathPrefixTest.rst
@@ -3,11 +3,6 @@
 rawPathPrefixTest
 =================
 
-Checks whether the unmatched path of the ``RequestContext`` has a prefix matched by the given ``PathMatcher``.
-Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
-the unmatched path.
-
-
 Signature
 ---------
 
@@ -17,6 +12,9 @@ Signature
 
 Description
 -----------
+Checks whether the unmatched path of the ``RequestContext`` has a prefix matched by the given ``PathMatcher``.
+Potentially extracts one or more values (depending on the type of the argument) but doesn't consume its match from
+the unmatched path.
 
 This directive is very similar to the :ref:`-pathPrefix-` directive with the one difference that the path prefix
 it matched (if it matched) is *not* consumed. The unmatched path of the ``RequestContext`` is therefore left as
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToNoTrailingSlashIfPresent.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToNoTrailingSlashIfPresent.rst
index cbbab223f2..a1ecfe524c 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToNoTrailingSlashIfPresent.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToNoTrailingSlashIfPresent.rst
@@ -3,11 +3,6 @@
 redirectToNoTrailingSlashIfPresent
 ==================================
 
-If the requested path does end with a trailing ``/`` character,
-redirects to the same path without that trailing slash..
-
-Opposite of :ref:`-redirectToTrailingSlashIfMissing-`.
-
 Signature
 ---------
 
@@ -16,6 +11,8 @@ Signature
 
 Description
 -----------
+If the requested path does end with a trailing ``/`` character,
+redirects to the same path without that trailing slash..
 
 Redirects the HTTP Client to the same resource yet without the trailing ``/``, in case the request contained it.
 When redirecting an HttpResponse with the given redirect response code (i.e. ``MovedPermanently`` or ``TemporaryRedirect``
@@ -27,6 +24,8 @@ for the re-directed-to route to match.
 
 A good read on the subject of how to deal with trailing slashes is available on `Google Webmaster Central - To Slash or not to Slash`_.
 
+See also :ref:`-redirectToTrailingSlashIfMissing-` for the opposite behaviour.
+
 .. _Google Webmaster Central - To Slash or not to Slash: http://googlewebmastercentral.blogspot.de/2010/04/to-slash-or-not-to-slash.html
 
 Example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToTrailingSlashIfMissing.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToTrailingSlashIfMissing.rst
index 2cfb5a4d1b..0792a5f246 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToTrailingSlashIfMissing.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/path-directives/redirectToTrailingSlashIfMissing.rst
@@ -3,11 +3,6 @@
 redirectToTrailingSlashIfMissing
 ================================
 
-If the requested path does not end with a trailing ``/`` character,
-redirects to the same path followed by such trailing slash.
-
-Opposite of :ref:`-redirectToNoTrailingSlashIfPresent-`.
-
 Signature
 ---------
 
@@ -16,6 +11,8 @@ Signature
 
 Description
 -----------
+If the requested path does not end with a trailing ``/`` character,
+redirects to the same path followed by such trailing slash.
 
 Redirects the HTTP Client to the same resource yet followed by a trailing ``/``, in case the request did not contain it.
 When redirecting an HttpResponse with the given redirect response code (i.e. ``MovedPermanently`` or ``TemporaryRedirect``
@@ -25,6 +22,8 @@ or refuses to for security reasons, automatically follow redirects.
 Please note that the inner paths **MUST** end with an explicit trailing slash (e.g. ``"things"./``) for the
 re-directed-to route to match.
 
+See also :ref:`-redirectToNoTrailingSlashIfPresent-` for the opposite behaviour.
+
 Example
 -------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/range-directives/withRangeSupport.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/range-directives/withRangeSupport.rst
index b6ca00208e..b078d9efd4 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/range-directives/withRangeSupport.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/range-directives/withRangeSupport.rst
@@ -3,10 +3,6 @@
 withRangeSupport
 ================
 
-Transforms the response from its inner route into a ``206 Partial Content``
-response if the client requested only part of the resource with a ``Range`` header.
-
-
 Signature
 ---------
 
@@ -23,6 +19,8 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 
 Description
 -----------
+Transforms the response from its inner route into a ``206 Partial Content``
+response if the client requested only part of the resource with a ``Range`` header.
 
 Augments responses to ``GET`` requests with an ``Accept-Ranges: bytes`` header and converts them into partial responses
 if the request contains a valid ``Range`` request header. The requested byte-ranges are coalesced (merged) if they
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeader.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeader.rst
index 84e5ea9fca..6e6788ea10 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeader.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeader.rst
@@ -3,10 +3,6 @@
 respondWithDefaultHeader
 ========================
 
-Adds a given HTTP header to all responses coming back from its inner route only if a header with the same name doesn't
-exist yet in the response.
-
-
 Signature
 ---------
 
@@ -16,14 +12,16 @@ Signature
 
 Description
 -----------
+Adds a given HTTP header to all responses coming back from its inner route only if a header with the same name doesn't
+exist yet in the response.
+
 
 This directive transforms ``HttpResponse`` and ``ChunkedResponseStart`` messages coming back from its inner route by
 potentially adding the given ``HttpHeader`` instance to the headers list.
 The header is only added if there is no header instance with the same name (case insensitively) already present in the
 response.
 
-If you'd like to add more than one header you can use the :ref:`-respondWithDefaultHeaders-` directive instead.
-
+See also :ref:`-respondWithDefaultHeaders-`  if you'd like to add more than one header.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeaders.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeaders.rst
index 93934a72b7..a9a83f844b 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeaders.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithDefaultHeaders.rst
@@ -3,10 +3,6 @@
 respondWithDefaultHeaders
 =========================
 
-Adds the given HTTP headers to all responses coming back from its inner route only if a respective header with the same
-name doesn't exist yet in the response.
-
-
 Signature
 ---------
 
@@ -16,11 +12,16 @@ Signature
 
 Description
 -----------
+Adds the given HTTP headers to all responses coming back from its inner route only if a respective header with the same
+name doesn't exist yet in the response.
+
 
 This directive transforms ``HttpResponse`` and ``ChunkedResponseStart`` messages coming back from its inner route by
 potentially adding the given ``HttpHeader`` instances to the headers list.
 A header is only added if there is no header instance with the same name (case insensitively) already present in the
-response. If you'd like to add only a single header you can use the :ref:`-respondWithDefaultHeader-` directive instead.
+response.
+
+See also :ref:`-respondWithDefaultHeader-` if you'd like to add only a single header.
 
 
 Example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeader.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeader.rst
index dbbf4d7d86..cd72217be7 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeader.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeader.rst
@@ -3,9 +3,6 @@
 respondWithHeader
 =================
 
-Adds a given HTTP header to all responses coming back from its inner route.
-
-
 Signature
 ---------
 
@@ -15,11 +12,12 @@ Signature
 
 Description
 -----------
+Adds a given HTTP header to all responses coming back from its inner route.
 
 This directive transforms ``HttpResponse`` and ``ChunkedResponseStart`` messages coming back from its inner route by
 adding the given ``HttpHeader`` instance to the headers list.
-If you'd like to add more than one header you can use the :ref:`-respondWithHeaders-` directive instead.
 
+See also :ref:`-respondWithHeaders-` if you'd like to add more than one header.
 
 Example
 -------
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeaders.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeaders.rst
index ce7e7268ad..8a2ee42efa 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeaders.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/respond-with-directives/respondWithHeaders.rst
@@ -3,9 +3,6 @@
 respondWithHeaders
 ==================
 
-Adds the given HTTP headers to all responses coming back from its inner route.
-
-
 Signature
 ---------
 
@@ -15,10 +12,12 @@ Signature
 
 Description
 -----------
+Adds the given HTTP headers to all responses coming back from its inner route.
 
 This directive transforms ``HttpResponse`` and ``ChunkedResponseStart`` messages coming back from its inner route by
 adding the given ``HttpHeader`` instances to the headers list.
-If you'd like to add just a single header you can use the :ref:`-respondWithHeader-` directive instead.
+
+See also :ref:`-respondWithHeader-` if you'd like to add just a single header.
 
 
 Example
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/complete.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/complete.rst
index def823f3d7..780f23e87f 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/complete.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/complete.rst
@@ -3,9 +3,6 @@
 complete
 ========
 
-Completes the request using the given argument(s).
-
-
 Signature
 ---------
 
@@ -27,6 +24,8 @@ The signature shown is simplified, the real signature uses magnets. [1]_
 Description
 -----------
 
+Completes the request using the given argument(s).
+
 ``complete`` uses the given arguments to construct a ``Route`` which simply calls ``complete`` on the ``RequestContext``
 with the respective ``HttpResponse`` instance.
 Completing the request will send the response "back up" the route structure where all the logic runs that wrapping
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/failWith.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/failWith.rst
index 7c6fe57258..72614c8a13 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/failWith.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/failWith.rst
@@ -3,10 +3,6 @@
 failWith
 ========
 
-Bubbles up the given error through the route structure where it is dealt with by the closest ``handleExceptions``
-directive and its :class:`ExceptionHandler`.
-
-
 Signature
 ---------
 
@@ -16,6 +12,8 @@ Signature
 
 Description
 -----------
+Bubbles up the given error through the route structure where it is dealt with by the closest ``handleExceptions``
+directive and its :class:`ExceptionHandler`.
 
 ``failWith`` explicitly raises an exception that gets bubbled up through the route structure to be picked up by the
 nearest ``handleExceptions`` directive. Using ``failWith`` rather than simply throwing an exception enables the route
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/redirect.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/redirect.rst
index 7df7800b92..af9364b118 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/redirect.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/redirect.rst
@@ -3,9 +3,6 @@
 redirect
 ========
 
-Completes the request with a redirection response to a given targer URI and of a given redirection type (status code).
-
-
 Signature
 ---------
 
@@ -15,6 +12,7 @@ Signature
 
 Description
 -----------
+Completes the request with a redirection response to a given targer URI and of a given redirection type (status code).
 
 ``redirect`` is a convenience helper for completing the request with a redirection response.
 It is equivalent to this snippet relying on the ``complete`` directive:
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/reject.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/reject.rst
index 38e5720933..d925b0b765 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/reject.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/route-directives/reject.rst
@@ -3,9 +3,6 @@
 reject
 ======
 
-Explicitly rejects the request optionally using the given rejection(s).
-
-
 Signature
 ---------
 
@@ -15,6 +12,7 @@ Signature
 
 Description
 -----------
+Explicitly rejects the request optionally using the given rejection(s).
 
 ``reject`` uses the given rejection instances (which might be the empty ``Seq``) to construct a ``Route`` which simply
 calls ``requestContext.reject``. See the chapter on :ref:`rejections-scala` for more information on what this means.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/extractScheme.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/extractScheme.rst
index dca844f40d..398d474f3a 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/extractScheme.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/extractScheme.rst
@@ -3,8 +3,6 @@
 extractScheme
 =============
 
-Extracts the value of the request Uri scheme.
-
 Signature
 ---------
 
@@ -13,9 +11,7 @@ Signature
 
 Description
 -----------
-
-The ``extractScheme`` directive can be used to determine the Uri scheme (i.e. "http", "https", etc.)
-for an incoming request.
+Extracts the Uri scheme (i.e. "``http``", "``https``", etc.) for an incoming request.
 
 For rejecting a request if it doesn't match a specified scheme name, see the :ref:`-scheme-` directive.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/scheme.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/scheme.rst
index b9a0ab8f57..b41437a4d2 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/scheme.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/scheme-directives/scheme.rst
@@ -3,8 +3,6 @@
 scheme
 ======
 
-Rejects a request if its Uri scheme does not match a given one.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Rejects a request if its Uri scheme does not match a given one.
 
 The ``scheme`` directive can be used to match requests by their Uri scheme, only passing
 through requests that match the specified scheme and rejecting all others.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst
index 4b5fa385f8..5aab3bf0ce 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst
@@ -3,8 +3,6 @@
 authenticateBasic
 =================
 
-Wraps the inner route with Http Basic authentication support using a given ``Authenticator[T]``.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with Http Basic authentication support using a given ``Authenticator[T]``.
 
 Provides support for handling `HTTP Basic Authentication`_.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst
index 96c48aee0a..60c30531e8 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst
@@ -3,8 +3,6 @@
 authenticateBasicAsync
 ======================
 
-Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticator[T]``.
-
 Signature
 ---------
 
@@ -15,8 +13,9 @@ Signature
 
 Description
 -----------
+Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticator[T]``.
 
-This variant of the :ref:`authenticateBasic` directive returns a ``Future[Option[T]]`` which allows freeing up the routing
+This variant of the :ref:`-authenticateBasic-` directive returns a ``Future[Option[T]]`` which allows freeing up the routing
 layer of Akka HTTP, freeing it for other requests. It should be used whenever an authentication is expected to take
 a longer amount of time (e.g. looking up the user in a database).
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst
index 9d2331a565..eaed96fd01 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst
@@ -3,8 +3,6 @@
 authenticateBasicPF
 ===================
 
-Wraps the inner route with Http Basic authentication support using a given ``AuthenticatorPF[T]``.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with Http Basic authentication support using a given ``AuthenticatorPF[T]``.
 
 Provides support for handling `HTTP Basic Authentication`_.
 
@@ -23,7 +22,7 @@ Refer to :ref:`-authenticateBasic-` for a detailed description of this directive
 Its semantics are equivalent to ``authenticateBasicPF`` 's, where not handling a case in the Partial Function (PF)
 leaves the request to be rejected with a :class:`AuthenticationFailedRejection` rejection.
 
-Longer-running authentication tasks (like looking up credentials in a database) should use :ref:`authenticateBasicAsync`
+Longer-running authentication tasks (like looking up credentials in a database) should use :ref:`-authenticateBasicAsync-`
 or :ref:`-authenticateBasicPFAsync-` if you prefer to use the ``PartialFunction`` syntax.
 
 .. warning::
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst
index 486d5f5aba..d01d244267 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst
@@ -3,8 +3,6 @@
 authenticateBasicPFAsync
 ========================
 
-Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticatorPF[T]``.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with Http Basic authentication support using a given ``AsyncAuthenticatorPF[T]``.
 
 Provides support for handling `HTTP Basic Authentication`_.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst
index 68f0dfeaff..898ef0e421 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst
@@ -3,8 +3,6 @@
 authenticateOAuth2
 ==================
 
-Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF[T]``
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF[T]``
 
 Provides support for extracting the so-called "*Bearer Token*" from the :class:`Authorization` HTTP Header,
 which is used to initiate an OAuth2 authorization.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst
index b4a2d16f0c..ff69316180 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst
@@ -3,8 +3,6 @@
 authenticateOAuth2Async
 =======================
 
-Wraps the inner route with OAuth Bearer Token authentication support using a given ``AsyncAuthenticator[T]``.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with OAuth Bearer Token authentication support using a given ``AsyncAuthenticator[T]``.
 
 Provides support for extracting the so-called "*Bearer Token*" from the :class:`Authorization` HTTP Header,
 which is used to initiate an OAuth2 authorization.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst
index 392d7e8c91..bc6ff6ad44 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst
@@ -3,8 +3,6 @@
 authenticateOAuth2PF
 ====================
 
-Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF[T]``.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Wraps the inner route with OAuth Bearer Token authentication support using a given ``AuthenticatorPF[T]``.
 
 Provides support for extracting the so-called "*Bearer Token*" from the :class:`Authorization` HTTP Header,
 which is used to initiate an OAuth2 authorization.
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2AsyncPF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst
similarity index 89%
rename from akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2AsyncPF.rst
rename to akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst
index e554611ad3..8c54e1b245 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2AsyncPF.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst
@@ -1,6 +1,6 @@
-.. _-authenticateOAuth2AsyncPF-:
+.. _-authenticateOAuth2PFAsync-:
 
-authenticateOAuth2AsyncPF
+authenticateOAuth2PFAsync
 =========================
 
 Wraps the inner route with OAuth Bearer Token authentication support using a given ``AsyncAuthenticatorPF[T]``.
@@ -11,7 +11,7 @@ Signature
 .. includecode:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala#authenticator
 
 .. includecode2:: /../../akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
-   :snippet: authenticateOAuth2AsyncPF
+   :snippet: authenticateOAuth2PFAsync
 
 Description
 -----------
@@ -38,5 +38,5 @@ For more information on how OAuth2 works see `RFC 6750`_.
 Example
 -------
 
-Usage in code is exactly the same as :ref:`-authenticateBasicAsyncPF-`,
+Usage in code is exactly the same as :ref:`-authenticateBasicPFAsync-`,
 with the difference that one must validate the token as OAuth2 dictates (which is currently not part of Akka HTTP itself).
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst
index 417f27cf74..5a46654737 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst
@@ -3,8 +3,6 @@
 authenticateOrRejectWithChallenge
 =================================
 
-Lifts an authenticator function into a directive.
-
 Signature
 ---------
 
@@ -15,6 +13,7 @@ Signature
 
 Description
 -----------
+Lifts an authenticator function into a directive.
 
 This directive allows implementing the low level challange-response type of authentication that some services may require.
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authorize.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authorize.rst
index c394611048..b45faf0ab6 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authorize.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authorize.rst
@@ -3,8 +3,6 @@
 authorize
 =========
 
-Applies the given authorization check to the request.
-
 Signature
 ---------
 
@@ -13,6 +11,7 @@ Signature
 
 Description
 -----------
+Applies the given authorization check to the request.
 
 The user-defined authorization check can either be supplied as a ``=> Boolean`` value which is calculated
 just from information out of the lexical scope, or as a function ``RequestContext => Boolean`` which can also
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst
index ecf687d456..9cf60006a8 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst
@@ -3,8 +3,6 @@
 extractCredentials
 ==================
 
-Extracts the potentially present ``HttpCredentials`` provided with the request's ``Authorization`` header.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessages.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessages.rst
index 36b8a6ef3f..9a94b83951 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessages.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessages.rst
@@ -3,9 +3,6 @@
 handleWebsocketMessages
 =======================
 
-Handles Websocket requests with the given handler and rejects other requests with an
-``ExpectedWebsocketRequestRejection``.
-
 Signature
 ---------
 
diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessagesForProtocol.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessagesForProtocol.rst
index b3717a8287..254761dfc2 100644
--- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessagesForProtocol.rst
+++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/websocket-directives/handleWebsocketMessagesForProtocol.rst
@@ -3,10 +3,6 @@
 handleWebsocketMessagesForProtocol
 ==================================
 
-Handles Websocket requests with the given handler if the given subprotocol is offered in the ``Sec-Websocket-Protocol``
-header of the request and rejects other requests with an ``ExpectedWebsocketRequestRejection`` or an
-``UnsupportedWebsocketSubprotocolRejection``.
-
 Signature
 ---------
 
@@ -15,6 +11,9 @@ Signature
 
 Description
 -----------
+Handles Websocket requests with the given handler if the given subprotocol is offered in the ``Sec-Websocket-Protocol``
+header of the request and rejects other requests with an ``ExpectedWebsocketRequestRejection`` or an
+``UnsupportedWebsocketSubprotocolRejection``.
 
 The directive first checks if the request was a valid Websocket handshake request and if the request offers the passed
 subprotocol name. If yes, the directive completes the request with the passed handler. Otherwise, the request is