=doc #18496 add scala docs for coding directives

akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala

@@ -14,6 +14,16 @@ import akka.util.ByteString
 import org.scalatest.matchers.Matcher
 
 class CodingDirectivesExamplesSpec extends RoutingSpec {
+  "responseEncodingAccepted" in {
+    val route = responseEncodingAccepted(gzip) { complete("content") }
+
+    Get("/") ~> route ~> check {
+      responseAs[String] shouldEqual "content"
+    }
+    Get("/") ~> `Accept-Encoding`(`identity;q=MIN`) ~> route ~> check {
+      rejection shouldEqual UnacceptedResponseEncodingRejection(gzip)
+    }
+  }
   "encodeResponse" in {
     val route = encodeResponse { complete("content") }
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/decodeRequest.rst

@@ -3,9 +3,6 @@
 decodeRequest
 =============
 
-Tries to decode the request with the specified ``Decoder`` or rejects the request with an
-``UnacceptedRequestEncodingRejection(supportedEncoding)``.
-
 Signature
 ---------
 
@@ -15,16 +12,10 @@ Signature
 Description
 -----------
 
-The ``decodeRequest`` directive is the building block for the ``decompressRequest`` directive.
+Decompresses the incoming request if it is ``gzip`` or ``deflate`` compressed. Uncompressed requests are passed through untouched. If the request encoded with another encoding the request is rejected with an ``UnsupportedRequestEncodingRejection``.
-
-``decodeRequest`` and ``decompressRequest`` are related like this::
-
-    decompressRequest(Gzip)          = decodeRequest(Gzip)
-    decompressRequest(a, b, c)       = decodeRequest(a) | decodeRequest(b) | decodeRequest(c)
-    decompressRequest()              = decodeRequest(Gzip) | decodeRequest(Deflate) | decodeRequest(NoEncoding)
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
-   :snippet: decodeRequest
+   :snippet: "decodeRequest"

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/decodeRequestWith.rst

@@ -3,8 +3,6 @@
 decodeRequestWith
 =================
 
-...
-
 Signature
 ---------
 
@@ -14,10 +12,10 @@ Signature
 Description
 -----------
 
-...
+Decodes the incoming request if it is encoded with one of the given encoders. If the request encoding doesn't match one of the given encoders the request is rejected with an ``UnsupportedRequestEncodingRejection``. If no decoders are given the default encoders (``Gzip``, ``Deflate``, ``NoCoding``) are used.
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
-   :snippet: 0decodeRequestWith
+   :snippet: decodeRequestWith

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponse.rst

@@ -3,9 +3,6 @@
 encodeResponse
 ==============
 
-Tries to encode the response with the specified ``Encoder`` or rejects the request with an
-``UnacceptedResponseEncodingRejection(supportedEncodings)``.
-
 Signature
 ---------
 
@@ -15,24 +12,16 @@ Signature
 Description
 -----------
 
-The directive automatically applies the ``autoChunkFileBytes`` directive as well to avoid having to load
+Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` header or rejects the request with an ``UnacceptedResponseEncodingRejection(supportedEncodings)``.
-an entire file into JVM heap.
 
-The parameter to the directive is either just an ``Encoder`` or all of an ``Encoder``, a threshold, and a
+The response encoding is determined by the rules specified in RFC7231_.
-chunk size to configure the automatically applied ``autoChunkFileBytes`` directive.
 
-The ``encodeResponse`` directive is the building block for the ``compressResponse`` and
+If the ``Accept-Encoding`` header is missing or empty or specifies an encoding other than identity, gzip or deflate then no encoding is used.
-``compressResponseIfRequested`` directives.
-
-``encodeResponse``, ``compressResponse``, and ``compressResponseIfRequested`` are related like this::
-
-    compressResponse(Gzip)          = encodeResponse(Gzip)
-    compressResponse(a, b, c)       = encodeResponse(a) | encodeResponse(b) | encodeResponse(c)
-    compressResponse()              = encodeResponse(Gzip) | encodeResponse(Deflate) | encodeResponse(NoEncoding)
-    compressResponseIfRequested()   = encodeResponse(NoEncoding) | encodeResponse(Gzip) | encodeResponse(Deflate)
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
-   :snippet: encodeResponse
+   :snippet: "encodeResponse"
+
+.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/encodeResponseWith.rst

@@ -3,8 +3,6 @@
 encodeResponseWith
 ==================
 
-...
-
 Signature
 ---------
 
@@ -14,10 +12,19 @@ Signature
 Description
 -----------
 
-...
+Encodes the response with the encoding that is requested by the client via the ``Accept-Encoding`` if it is among the provided encoders or rejects the request with an ``UnacceptedResponseEncodingRejection(supportedEncodings)``.
+
+The response encoding is determined by the rules specified in RFC7231_.
+
+If the ``Accept-Encoding`` header is missing then the response is encoded using the ``first`` encoder.
+
+If the ``Accept-Encoding`` header is empty and ``NoCoding`` is part of the encoders then no
+response encoding is used. Otherwise the request is rejected.
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
    :snippet: encodeResponseWith
+
+.. _RFC7231: http://tools.ietf.org/html/rfc7231#section-5.3.4

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/requestEncodedWith.rst

@@ -3,9 +3,6 @@
 requestEncodedWith
 ==================
 
-Passes the request to the inner route if the request is encoded with the argument encoding. Otherwise,
-rejects the request with an ``UnacceptedRequestEncodingRejection(encoding)``.
-
 Signature
 ---------
 
@@ -15,4 +12,8 @@ Signature
 Description
 -----------
 
-This directive is the building block for ``decodeRequest`` to reject unsupported encodings.
+Passes the request to the inner route if the request is encoded with the argument encoding. Otherwise, rejects the request with an ``UnacceptedRequestEncodingRejection(encoding)``.
+
+This directive is the `building block`_ for ``decodeRequest`` to reject unsupported encodings.
+
+.. _`building block`: @github@/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala

akka-docs-dev/rst/scala/http/routing-dsl/directives/coding-directives/responseEncodingAccepted.rst

@@ -3,9 +3,6 @@
 responseEncodingAccepted
 ========================
 
-Passes the request to the inner route if the request accepts the argument encoding. Otherwise,
-rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
-
 Signature
 ---------
 
@@ -15,4 +12,10 @@ Signature
 Description
 -----------
 
-This directive is the building block for ``encodeResponse`` to reject unsupported encodings.
+Passes the request to the inner route if the request accepts the argument encoding. Otherwise, rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
+
+Example
+-------
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/CodingDirectivesExamplesSpec.scala
+  :snippet: responseEncodingAccepted