+htp #18837 more docs and final cleanups, complete java docs

akka-docs/rst/scala/http/routing-dsl/index.rst

@@ -23,6 +23,7 @@ static content serving.
    exception-handling
    path-matchers
    case-class-extraction
+   source-streaming-support
    testkit
    websocket-support
 

akka-docs/rst/scala/http/routing-dsl/source-streaming-support.rst

@@ -1,11 +1,27 @@
 .. _json-streaming-scala:
 
+Source Streaming
+================
+
+Akka HTTP supports completing a request with an Akka ``Source[T, _]``, which makes it possible to very easily build
+streaming end-to-end APIs which apply back-pressure throughout the entire stack. 
+
+It is possible to complete requests with raw ``Source[ByteString, _]``, however often it is more convenient to 
+stream on an element-by-element basis, and allow Akka HTTP to handle the rendering internally - for example as a JSON array,
+or CSV stream (where each element is separated by a new-line).
+
+In the following sections we investigate how to make use of the JSON Streaming infrastructure,
+however the general hints apply to any kind of element-by-element streaming you could imagine.
+
+It is possible to implement your own framing for any content type you might need, including bianary formats 
+by implementing :class:`FramingWithContentType`.
+
 JSON Streaming
 ==============
 
 `JSON Streaming`_ is a term refering to streaming a (possibly infinite) stream of element as independent JSON
-objects onto one continious HTTP connection. The elements are most often separated using newlines,
-however do not have to be and concatenating elements side-by-side or emitting "very long" JSON array is also another
+objects as a continuous HTTP request or response. The elements are most often separated using newlines,
+however do not have to be. Concatenating elements side-by-side or emitting "very long" JSON array is also another
 use case.
 
 In the below examples, we'll be refering to the ``User`` and ``Measurement`` case classes as our model, which are defined as:
@@ -30,7 +46,6 @@ Firstly, we'll need to get some additional marshalling infrastructure set up, th
 Akka Streams ``Source[T,_]``. One such trait, containing the needed marshallers is ``SprayJsonSupport``, which uses
 spray-json (a high performance json parser library), and is shipped as part of Akka HTTP in the
 ``akka-http-spray-json-experimental`` module.
-to and from ``Source[T,_]`` by using spray-json provided
 
 Next we import our model's marshallers, generated by spray-json.
 
@@ -68,7 +83,7 @@ in case one element in front of the stream takes a long time to marshall, yet ot
 Consuming JSON Streaming uploads
 --------------------------------
 
-Sometimes the client may be sending in a streaming request, for example an embedded device initiated a connection with
+Sometimes the client may be sending a streaming request, for example an embedded device initiated a connection with
 the server and is feeding it with one line of measurement data.
 
 In this example, we want to consume this data in a streaming fashion from the request entity, and also apply