=doc a first set of new and imported documentation for akka-http

akka-docs-dev/rst/scala/http/directives/debugging-directives/index.rst

@@ -0,0 +1,11 @@
+.. _DebuggingDirectives:
+
+DebuggingDirectives
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   logRequest
+   logRequestResult
+   logResult

akka-docs-dev/rst/scala/http/directives/debugging-directives/logRequest.rst

@@ -0,0 +1,46 @@
+.. _-logRequest-:
+
+logRequest
+==========
+
+Logs the request.
+
+Signature
+---------
+
+::
+
+    def logRequest(marker: String)(implicit log: LoggingContext): Directive0
+    def logRequest(marker: String, level: LogLevel)(implicit log: LoggingContext): Directive0
+    def logRequest(show: HttpRequest => String)(implicit log: LoggingContext): Directive0
+    def logRequest(show: HttpRequest => LogEntry)(implicit log: LoggingContext): Directive0
+    def logRequest(magnet: LoggingMagnet[HttpRequest => Unit])(implicit log: LoggingContext): Directive0
+
+The signature shown is simplified, the real signature uses magnets. [1]_
+
+.. [1] See `The Magnet Pattern`_ for an explanation of magnet-based overloading.
+.. _`The Magnet Pattern`: /blog/2012-12-13-the-magnet-pattern/
+
+Description
+-----------
+
+Logs the request using the supplied ``LoggingMagnet[HttpRequest => Unit]``.  This ``LoggingMagnet`` is a wrapped
+function ``HttpRequest => Unit`` that can be implicitly created from the different constructors shown above. These
+constructors build a ``LoggingMagnet`` from these components:
+
+  * A marker to prefix each log message with.
+  * A log level.
+  * A ``show`` function that calculates a string representation for a request.
+  * An implicit ``LoggingContext`` that is used to emit the log message.
+  * A function that creates a ``LogEntry`` which is a combination of the elements above.
+
+It is also possible to use any other function ``HttpRequest => Unit`` for logging by wrapping it with ``LoggingMagnet``.
+See the examples for ways to use the ``logRequest`` directive.
+
+Use ``logResult`` for logging the response, or ``logRequestResult`` for logging both.
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/DebuggingDirectivesExamplesSpec.scala
+   :snippet: logRequest-0

akka-docs-dev/rst/scala/http/directives/debugging-directives/logRequestResult.rst

@@ -0,0 +1,34 @@
+.. _-logRequestResult-:
+
+logRequestResult
+==================
+
+Logs request and response.
+
+Signature
+---------
+
+::
+
+    def logRequestResult(marker: String)(implicit log: LoggingContext): Directive0
+    def logRequestResult(marker: String, level: LogLevel)(implicit log: LoggingContext): Directive0
+    def logRequestResult(show: HttpRequest ⇒ HttpResponsePart ⇒ Option[LogEntry])
+                          (implicit log: LoggingContext): Directive0
+    def logRequestResult(show: HttpRequest ⇒ Any ⇒ Option[LogEntry])(implicit log: LoggingContext): Directive0
+
+The signature shown is simplified, the real signature uses magnets. [1]_
+
+.. [1] See `The Magnet Pattern`_ for an explanation of magnet-based overloading.
+.. _`The Magnet Pattern`: /blog/2012-12-13-the-magnet-pattern/
+
+Description
+-----------
+
+This directive is a combination of ``logRequest`` and ``logResult``. See ``logRequest`` for the general description
+how these directives work.
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/DebuggingDirectivesExamplesSpec.scala
+   :snippet: logRequestResult

akka-docs-dev/rst/scala/http/directives/debugging-directives/logResult.rst

@@ -0,0 +1,38 @@
+.. _-logResult-:
+
+logResult
+===========
+
+Logs the response.
+
+Signature
+---------
+
+::
+
+    def logResult(marker: String)(implicit log: LoggingContext): Directive0
+    def logResult(marker: String, level: LogLevel)(implicit log: LoggingContext): Directive0
+    def logResult(show: Any => String)(implicit log: LoggingContext): Directive0
+    def logResult(show: Any => LogEntry)(implicit log: LoggingContext): Directive0
+    def logResult(magnet: LoggingMagnet[Any => Unit])(implicit log: LoggingContext): Directive0
+
+The signature shown is simplified, the real signature uses magnets. [1]_
+
+.. [1] See `The Magnet Pattern`_ for an explanation of magnet-based overloading.
+.. _`The Magnet Pattern`: /blog/2012-12-13-the-magnet-pattern/
+
+Description
+-----------
+
+See ``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 anything passing through :ref:`The Responder Chain` (which can either be a ``HttpResponsePart`` or a ``Rejected``
+message reporting rejections).
+
+Use ``logRequest`` for logging the request, or ``logRequestResult`` for logging both.
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/DebuggingDirectivesExamplesSpec.scala
+   :snippet: logResult