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

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.