=docs #18012 complete remaining TODO sections in scala HTTP docs

akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala

@@ -140,19 +140,7 @@ class HttpExt(config: Config)(implicit system: ActorSystem) extends akka.actor.E
                          log: LoggingAdapter = system.log)(implicit fm: Materializer): Future[ServerBinding] =
     bindAndHandle(Flow[HttpRequest].mapAsync(parallelism)(handler), interface, port, settings, httpsContext, log)
 
-  /**
-   * The type of the server-side HTTP layer as a stand-alone BidiStage
-   * that can be put atop the TCP layer to form an HTTP server.
-   *
-   * {{{
-   *                +------+
-   * HttpResponse ~>|      |~> SslTlsOutbound
-   *                | bidi |
-   * HttpRequest  <~|      |<~ SslTlsInbound
-   *                +------+
-   * }}}
-   */
-  type ServerLayer = BidiFlow[HttpResponse, SslTlsOutbound, SslTlsInbound, HttpRequest, Unit]
+  type ServerLayer = Http.ServerLayer
 
   /**
    * Constructs a [[ServerLayer]] stage using the configured default [[ServerSettings]]. The returned [[BidiFlow]]
@@ -207,19 +195,7 @@ class HttpExt(config: Config)(implicit system: ActorSystem) extends akka.actor.E
     }
   }
 
-  /**
-   * The type of the client-side HTTP layer as a stand-alone BidiStage
-   * that can be put atop the TCP layer to form an HTTP client.
-   *
-   * {{{
-   *                +------+
-   * HttpRequest  ~>|      |~> SslTlsOutbound
-   *                | bidi |
-   * HttpResponse <~|      |<~ SslTlsInbound
-   *                +------+
-   * }}}
-   */
-  type ClientLayer = BidiFlow[HttpRequest, SslTlsOutbound, SslTlsInbound, HttpResponse, Unit]
+  type ClientLayer = Http.ClientLayer
 
   /**
    * Constructs a [[ClientLayer]] stage using the configured default [[ClientConnectionSettings]].
@@ -502,6 +478,38 @@ class HttpExt(config: Config)(implicit system: ActorSystem) extends akka.actor.E
 
 object Http extends ExtensionId[HttpExt] with ExtensionIdProvider {
 
+  //#server-layer
+  /**
+   * The type of the server-side HTTP layer as a stand-alone BidiStage
+   * that can be put atop the TCP layer to form an HTTP server.
+   *
+   * {{{
+   *                +------+
+   * HttpResponse ~>|      |~> SslTlsOutbound
+   *                | bidi |
+   * HttpRequest  <~|      |<~ SslTlsInbound
+   *                +------+
+   * }}}
+   */
+  type ServerLayer = BidiFlow[HttpResponse, SslTlsOutbound, SslTlsInbound, HttpRequest, Unit]
+  //#
+
+  //#client-layer
+  /**
+   * The type of the client-side HTTP layer as a stand-alone BidiStage
+   * that can be put atop the TCP layer to form an HTTP client.
+   *
+   * {{{
+   *                +------+
+   * HttpRequest  ~>|      |~> SslTlsOutbound
+   *                | bidi |
+   * HttpResponse <~|      |<~ SslTlsInbound
+   *                +------+
+   * }}}
+   */
+  type ClientLayer = BidiFlow[HttpRequest, SslTlsOutbound, SslTlsInbound, HttpResponse, Unit]
+  //#
+
   /**
    * Represents a prospective HTTP server binding.
    *

akka-http-core/src/main/scala/akka/http/scaladsl/model/HttpEntity.scala

@@ -115,13 +115,23 @@ sealed trait HttpEntity extends jm.HttpEntity {
 sealed trait BodyPartEntity extends HttpEntity with jm.BodyPartEntity {
   def withContentType(contentType: ContentType): BodyPartEntity
 }
-/* An entity that can be used for requests */
+
+/**
+ * An [[HttpEntity]] that can be used for requests.
+ * Note that all entities that can be used for requests can also be used for responses.
+ * (But not the other way around, since [[HttpEntity.CloseDelimited]] can only be used for responses!)
+ */
 sealed trait RequestEntity extends HttpEntity with jm.RequestEntity with ResponseEntity {
   def withContentType(contentType: ContentType): RequestEntity
 
   override def transformDataBytes(transformer: Flow[ByteString, ByteString, Any]): RequestEntity
 }
-/* An entity that can be used for responses */
+
+/**
+ * An [[HttpEntity]] that can be used for responses.
+ * Note that all entities that can be used for requests can also be used for responses.
+ * (But not the other way around, since [[HttpEntity.CloseDelimited]] can only be used for responses!)
+ */
 sealed trait ResponseEntity extends HttpEntity with jm.ResponseEntity {
   def withContentType(contentType: ContentType): ResponseEntity
 

akka-http-core/src/main/scala/akka/http/scaladsl/model/Multipart.scala

@@ -21,7 +21,7 @@ import akka.http.scaladsl.model.headers._
 import akka.http.impl.engine.rendering.BodyPartRenderer
 import FastFuture._
 
-trait Multipart {
+sealed trait Multipart {
   def mediaType: MultipartMediaType
   def parts: Source[Multipart.BodyPart, Any]
 

akka-http/src/main/scala/akka/http/scaladsl/marshalling/Marshaller.scala

@@ -63,6 +63,7 @@ sealed abstract class Marshaller[-A, +B] {
     Marshaller(implicit ec ⇒ c ⇒ apply(f(ec)(c)))
 }
 
+//# marshaller-creation
 object Marshaller
   extends GenericMarshallers
   with PredefinedToEntityMarshallers
@@ -117,7 +118,9 @@ object Marshaller
   def opaque[A, B](marshal: A ⇒ B): Marshaller[A, B] =
     strict { value ⇒ Marshalling.Opaque(() ⇒ marshal(value)) }
 }
+//#
 
+//# marshalling
 /**
  * Describes one possible option for marshalling a given value.
  */
@@ -151,3 +154,4 @@ object Marshalling {
     def map[B](f: A ⇒ B): Opaque[B] = copy(marshal = () ⇒ f(marshal()))
   }
 }
+//#

akka-http/src/main/scala/akka/http/scaladsl/marshalling/PredefinedToEntityMarshallers.scala

@@ -58,7 +58,7 @@ trait PredefinedToEntityMarshallers extends MultipartMarshallers {
       HttpEntity(ContentType(`application/x-www-form-urlencoded`, charset), string)
     }
 
-  implicit val HttpEntityMarshaller: ToEntityMarshaller[MessageEntity] = Marshaller strict { value ⇒
+  implicit val MessageEntityMarshaller: ToEntityMarshaller[MessageEntity] = Marshaller strict { value ⇒
     Marshalling.WithFixedCharset(value.contentType.mediaType, value.contentType.charset, () ⇒ value)
   }
 }

akka-http/src/main/scala/akka/http/scaladsl/marshalling/package.scala

@@ -8,8 +8,10 @@ import scala.collection.immutable
 import akka.http.scaladsl.model._
 
 package object marshalling {
+  //# marshaller-aliases
   type ToEntityMarshaller[T] = Marshaller[T, MessageEntity]
   type ToHeadersAndEntityMarshaller[T] = Marshaller[T, (immutable.Seq[HttpHeader], MessageEntity)]
   type ToResponseMarshaller[T] = Marshaller[T, HttpResponse]
   type ToRequestMarshaller[T] = Marshaller[T, HttpRequest]
+  //#
 }

akka-http/src/main/scala/akka/http/scaladsl/unmarshalling/Unmarshaller.scala

@@ -35,6 +35,9 @@ object Unmarshaller
   with PredefinedFromEntityUnmarshallers
   with PredefinedFromStringUnmarshallers {
 
+  // format: OFF
+
+  //#unmarshaller-creation
   /**
    * Creates an `Unmarshaller` from the given function.
    */
@@ -55,18 +58,20 @@ object Unmarshaller
    * in the given order. The first successful unmarshalling of a "sub-unmarshallers" is the one produced by the
    * "super-unmarshaller".
    */
-  def firstOf[A, B](unmarshallers: Unmarshaller[A, B]*): Unmarshaller[A, B] =
-    Unmarshaller { implicit ec ⇒
-      a ⇒
-        def rec(ix: Int, supported: Set[ContentTypeRange]): Future[B] =
-          if (ix < unmarshallers.size) {
-            unmarshallers(ix)(a).fast.recoverWith {
-              case Unmarshaller.UnsupportedContentTypeException(supp) ⇒ rec(ix + 1, supported ++ supp)
-            }
-          } else FastFuture.failed(Unmarshaller.UnsupportedContentTypeException(supported))
-        rec(0, Set.empty)
+  def firstOf[A, B](unmarshallers: Unmarshaller[A, B]*): Unmarshaller[A, B] = //...
+  //#
+    Unmarshaller { implicit ec ⇒ a ⇒
+      def rec(ix: Int, supported: Set[ContentTypeRange]): Future[B] =
+        if (ix < unmarshallers.size) {
+          unmarshallers(ix)(a).fast.recoverWith {
+            case Unmarshaller.UnsupportedContentTypeException(supp) ⇒ rec(ix + 1, supported ++ supp)
+          }
+        } else FastFuture.failed(Unmarshaller.UnsupportedContentTypeException(supported))
+      rec(0, Set.empty)
     }
 
+  // format: ON
+
   implicit def identityUnmarshaller[T]: Unmarshaller[T, T] = Unmarshaller(_ ⇒ FastFuture.successful)
 
   // we don't define these methods directly on `Unmarshaller` due to variance constraints

akka-http/src/main/scala/akka/http/scaladsl/unmarshalling/package.scala

@@ -8,10 +8,12 @@ import akka.http.scaladsl.common.StrictForm
 import akka.http.scaladsl.model._
 
 package object unmarshalling {
+  //# unmarshaller-aliases
   type FromEntityUnmarshaller[T] = Unmarshaller[HttpEntity, T]
   type FromMessageUnmarshaller[T] = Unmarshaller[HttpMessage, T]
   type FromResponseUnmarshaller[T] = Unmarshaller[HttpResponse, T]
   type FromRequestUnmarshaller[T] = Unmarshaller[HttpRequest, T]
   type FromStringUnmarshaller[T] = Unmarshaller[String, T]
   type FromStrictFormFieldUnmarshaller[T] = Unmarshaller[StrictForm.Field, T]
+  //#
 }