Fix and improve Spray JSON docs

akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala

@@ -54,8 +54,10 @@ trait SprayJsonSupport {
       } else FastFuture.failed(Unmarshaller.UnsupportedContentTypeException(support.supported))
     }
 
+  //#sprayJsonMarshallerConverter
   implicit def sprayJsonMarshallerConverter[T](writer: RootJsonWriter[T])(implicit printer: JsonPrinter = CompactPrinter): ToEntityMarshaller[T] =
     sprayJsonMarshaller[T](writer, printer)
+  //#sprayJsonMarshallerConverter
   implicit def sprayJsonMarshaller[T](implicit writer: RootJsonWriter[T], printer: JsonPrinter = CompactPrinter): ToEntityMarshaller[T] =
     sprayJsValueMarshaller compose writer.write
   implicit def sprayJsValueMarshaller(implicit printer: JsonPrinter = CompactPrinter): ToEntityMarshaller[JsValue] =

docs/src/main/paradox/scala/http/common/json-support.md

@@ -1,37 +1,47 @@
 <a id="akka-http-spray-json"></a>
 # JSON Support
 
-Akka HTTP's @ref[marshalling](marshalling.md#http-marshalling-scala) and @ref[unmarshalling](unmarshalling.md#http-unmarshalling-scala)
-infrastructure makes it rather easy to seamlessly support specific wire representations of your data objects, like JSON,
-XML or even binary encodings.
+Akka HTTP's @ref[marshalling](marshalling.md#http-marshalling-scala) and @ref[unmarshalling](unmarshalling.md#http-unmarshalling-scala) infrastructure makes it rather easy to seamlessly support specific wire representations of your data objects, like JSON, XML or even binary encodings.
 
-For JSON Akka HTTP currently provides support for [spray-json](https://github.com/spray/spray-json) right out of the box through it's
-`akka-http-spray-json` module.
+For JSON Akka HTTP currently provides support for [spray-json] right out of the box through its `akka-http-spray-json` module.
 
-Other JSON libraries are supported by the community.
-See [the list of current community extensions for Akka HTTP](http://akka.io/community/#extensions-to-akka-http).
+Other JSON libraries are supported by the community. See [the list of current community extensions for Akka HTTP](http://akka.io/community/#extensions-to-akka-http).
 
 ## spray-json Support
 
 The [SprayJsonSupport](@github@/akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala) trait provides a `FromEntityUnmarshaller[T]` and `ToEntityMarshaller[T]` for every type `T`
 that an implicit `spray.json.RootJsonReader` and/or `spray.json.RootJsonWriter` (respectively) is available for.
 
-This is how you enable automatic support for (un)marshalling from and to JSON with [spray-json](https://github.com/spray/spray-json):
+To enable automatic support for (un)marshalling from and to JSON with [spray-json], add a library dependency onto:
 
- 1. Add a library dependency onto `"com.typesafe.akka" %% "akka-http-spray-json-experimental" % "@version@"`. <!-- FIXME: use preprocessing -->
- 2. `import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport._` or mix in the
-`akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport` trait.
- 3. Provide a `RootJsonFormat[T]` for your type and bring it into scope.
-Check out the [spray-json](https://github.com/spray/spray-json) documentation for more info on how to do this.
+@@@vars
+```sbt
+"com.typesafe.akka" %% "akka-http-spray-json-experimental" % "$project.version$"`
+```
+@@@
+
+Next, provide a `RootJsonFormat[T]` for your type and bring it into scope. Check out the [spray-json] documentation for more info on how to do this.
+
+Finally, mix in the `akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport` trait as shown in the example below or import the `FromEntityUnmarshaller[T]` and `ToEntityMarshaller[T]` implicits directly from `SprayJsonSupport`
+
+```scala
+import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport._
+```
 
 Once you have done this (un)marshalling between JSON and your type `T` should work nicely and transparently.
 
 @@snip [SprayJsonExampleSpec.scala](../../../../../test/scala/docs/http/scaladsl/SprayJsonExampleSpec.scala) { #minimal-spray-json-example }
 
- 4. By default, spray-json marshals your types to pretty printed json by implicit conversion using PrettyPrinter, as defined in
-`implicit def sprayJsonMarshallerConverter[T](writer: RootJsonWriter[T])(implicit printer: JsonPrinter = PrettyPrinter): ToEntityMarshaller[T]`.
-Alternately to marshal your types to compact printed json, bring a `CompactPrinter` in scope to perform implicit conversion.
+### Pretty printing
+
+By default, spray-json marshals your types to compact printed JSON by implicit conversion using `CompactPrinter`, as defined in:
+
+@@snip [SprayJsonSupport.scala](../../../../../../../akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala) { #sprayJsonMarshallerConverter }
+
+Alternatively to marshal your types to pretty printed JSON, bring a `PrettyPrinter` in scope to perform implicit conversion.
+
+@@snip [SprayJsonPrettyMarshalSpec.scala](../../../../../test/scala/docs/http/scaladsl/SprayJsonPrettyMarshalSpec.scala) { #example }
 
-@@snip [SprayJsonCompactMarshalSpec.scala](../../../../../test/scala/docs/http/scaladsl/SprayJsonCompactMarshalSpec.scala) { #example }
+To learn more about how spray-json works please refer to its [documentation][spray-json].
 
-To learn more about how spray-json works please refer to its [documentation ](https://github.com/spray/spray-json).
+[spray-json]: https://github.com/spray/spray-json

docs/src/test/scala/docs/http/scaladsl/SprayJsonPrettyMarshalSpec.scala

@@ -0,0 +1,51 @@
+/*
+ * Copyright (C) 2009-2016 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.http.scaladsl
+
+import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
+import akka.http.scaladsl.server.Directives
+import org.scalatest.{ Matchers, WordSpec }
+
+class SprayJsonPrettyMarshalSpec extends server.RoutingSpec {
+
+  "spray-json example" in {
+    //#example
+    import spray.json._
+
+    // domain model
+    final case class PrettyPrintedItem(name: String, id: Long)
+
+    trait PrettyJsonFormatSupport extends DefaultJsonProtocol with SprayJsonSupport {
+      implicit val printer = PrettyPrinter
+      implicit val prettyPrintedItemFormat = jsonFormat2(PrettyPrintedItem)
+    }
+
+    // use it wherever json (un)marshalling is needed
+    class MyJsonService extends Directives with PrettyJsonFormatSupport {
+
+      // format: OFF
+      val route =
+        get {
+          pathSingleSlash {
+            complete {
+              PrettyPrintedItem("akka", 42) // will render as JSON
+            }
+          }
+        }
+      // format: ON
+    }
+
+    val service = new MyJsonService
+
+    // verify the pretty printed JSON
+    Get("/") ~> service.route ~> check {
+      responseAs[String] shouldEqual
+        """{
+          |  "name": "akka",
+          |  "id": 42
+          |}""".stripMargin
+    }
+    //#example
+  }
+}