+doc add overview documentation for java-side directives (+ some cleanup)

akka-docs-dev/rst/java/http/index.rst

@@ -3,13 +3,39 @@
 Akka HTTP
 =========
 
+The Akka HTTP modules implement a full server- and client-side HTTP stack on top of *akka-actor* and *akka-stream*. It's
+not a web-framework but rather a more general toolkit for providing and consuming HTTP-based services. While interaction
+with a browser is of course also in scope it is not the primary focus of Akka HTTP.
+
+Akka HTTP follows a rather open design and many times offers several different API levels for "doing the same thing".
+You get to pick the API level of abstraction that is most suitable for your application.
+This means that, if you have trouble achieving something using a high-level API, there's a good chance that you can get
+it done with a low-level API, which offers more flexibility but might require you to write more application code.
+
+Akka HTTP is structured into several modules:
+
+akka-http-core
+  A complete, mostly low-level, server- and client-side implementation of HTTP (incl. WebSockets).
+  Includes a model of all things HTTP.
+
+akka-http
+  Higher-level functionality, like (un)marshalling, (de)compression as well as a powerful DSL
+  for defining HTTP-based APIs on the server-side
+
+akka-http-testkit
+  A test harness and set of utilities for verifying server-side service implementations
+
+akka-http-jackson
+  Predefined glue-code for (de)serializing custom types from/to JSON with jackson_
+
 .. toctree::
    :maxdepth: 2
 
-   introduction
    configuration
    http-model
    server-side/low-level-server-side-api
    server-side/websocket-support
    routing-dsl/index
-   client-side/index
+   client-side/index
+
+.. _jackson: https://github.com/FasterXML/jackson

akka-docs-dev/rst/java/http/introduction.rst

@@ -1,28 +0,0 @@
-Introduction
-============
-
-The Akka HTTP modules implement a full server- and client-side HTTP stack on top of *akka-actor* and *akka-stream*. It's
-not a web-framework but rather a more general toolkit for providing and consuming HTTP-based services. While interaction
-with a browser is of course also in scope it is not the primary focus of Akka HTTP.
-
-Akka HTTP follows a rather open design and many times offers several different API levels for "doing the same thing".
-You get to pick the API level of abstraction that is most suitable for your application.
-This means that, if you have trouble achieving something using a high-level API, there's a good chance that you can get
-it done with a low-level API, which offers more flexibility but might require you to write more application code.
-
-Akka HTTP is structured into several modules:
-
-akka-http-core
-  A complete, mostly low-level, server- and client-side implementation of HTTP (incl. WebSockets)
-
-akka-http
-  Higher-level functionality, like (un)marshalling, (de)compression as well as a powerful DSL
-  for defining HTTP-based APIs on the server-side
-
-akka-http-testkit
-  A test harness and set of utilities for verifying server-side service implementations
-
-akka-http-jackson
-  Predefined glue-code for (de)serializing custom types from/to JSON with jackson_
-
-.. _jackson: https://github.com/FasterXML/jackson

akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst

@@ -3,4 +3,57 @@
 Directives
 ==========
 
-TODO
+A directive is a wrapper for a route or a list of alternative routes that adds one or more of the following
+functionality to its nested route(s):
+
+ * it filters the request and lets only matching requests pass (e.g. the `get` directive lets only GET-requests pass)
+ * it modifies the request or the ``RequestContext`` (e.g. the `path` directives filters on the unmatched path and then
+   passes an updated ``RequestContext`` unmatched path)
+ * it modifies the response coming out of the nested route
+
+akka-http provides a set of predefined directives for various tasks. You can access them by either extending from
+``akka.http.javadsl.server.AllDirectives`` or by importing them statically with
+``import static akka.http.javadsl.server.Directives.*;``.
+
+These classes of directives are currently defined:
+
+BasicDirectives
+  Contains methods to create routes that complete with a static values or allow specifying :ref:`handlers-java` to
+  process a request.
+
+CacheConditionDirectives
+  Contains a single directive ``conditional`` that wraps its inner route with support for Conditional Requests as defined
+  by http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26.
+
+CodingDirectives
+  Contains directives to decode compressed requests and encode responses.
+
+CookieDirectives
+  Contains a single directive ``setCookie`` to aid adding a cookie to a response.
+
+ExecutionDirectives
+  Contains directives to deal with exceptions that occurred during routing.
+
+FileAndResourceDirectives
+  Contains directives to serve resources from files on the file system or from the classpath.
+
+HostDirectives
+  Contains directives to filter on the ``Host`` header of the incoming request.
+
+MethodDirectives
+  Contains directives to filter on the HTTP method of the incoming request.
+
+MiscDirectives
+  Contains directives that validate a request by user-defined logic.
+
+PathDirectives
+  Contains directives to match and filter on the URI path of the incoming request.
+
+RangeDirectives
+  Contains a single directive ``withRangeSupport`` that adds support for retrieving partial responses.
+
+SchemeDirectives
+  Contains a single directive ``scheme`` to filter requests based on the URI scheme (http vs. https).
+
+WebsocketDirectives
+  Contains directives to support answering Websocket requests.

akka-docs-dev/rst/java/http/routing-dsl/handlers.rst

@@ -59,7 +59,7 @@ route structure, this time representing segments from the URI path.
 Handlers in Java 8
 ------------------
 
-In Java 8 handlers can be provided as function literals. The example from before then looks like this:
+In Java 8 handlers can be provided as function literals. The previous example can then be written like this:
 
 .. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleSpec.java
    :include: handler2-example-full

akka-docs-dev/rst/java/http/routing-dsl/index.rst

@@ -3,7 +3,7 @@
 High-level Server-Side API
 ==========================
 
-...
+To use the high-level API you need to add a dependency to the ``akka-http-experimental`` module.
 
 .. toctree::
    :maxdepth: 1

akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst

@@ -27,11 +27,19 @@ service.
 
 These request values are defined:
 
- * in ``RequestVals``: request values for basic data like URI components, request method, peer address, or the entity data
- * in ``Cookies``: request values representing cookies
- * in ``FormFields``: request values to access form fields unmarshalled to various primitive Java types
- * in ``Headers``:: request values to access request headers or header values
- * ``HttpBasicAuthenticator``: an abstract class to implement to create a request value representing a HTTP basic authenticated principal
- * in ``Parameters``: request values to access URI paramaters unmarshalled to various primitive Java types
- * in ``PathMatchers``: request values to match and access URI path segments
- * ``CustomRequestVal``: an abstract class to implement arbitrary custom request values
+RequestVals
+  Contains request values for basic data like URI components, request method, peer address, or the entity data.
+Cookies
+  Contains request values representing cookies.
+FormFields
+  Contains request values to access form fields unmarshalled to various primitive Java types.
+Headers
+  Contains request values to access request headers or header values.
+HttpBasicAuthenticator
+  An abstract class to implement to create a request value representing a HTTP basic authenticated principal.
+Parameters
+  Contains request values to access URI paramaters unmarshalled to various primitive Java types.
+PathMatchers
+  Contains request values to match and access URI path segments.
+CustomRequestVal
+  An abstract class to implement arbitrary custom request values.