Merge pull request #3858 from jooby-project/newdoc

documentation: find a way to organize/group/classify documentation be…

Author: jknack

docs/asciidoc/body.adoc

@@ -1,24 +1,24 @@
-=== Request Body
+==== Request Body
 
-Raw `request body` is available via javadoc:Context[body] method:
+The raw request body is available via the javadoc:Context[body] method:
 
 .Java
 [source,java,role="primary"]
 ----
 {
   post("/string", ctx -> {
     String body = ctx.body().value();        // <1>
-    ...
+    // ...
   });
   
   post("/bytes", ctx -> {
     byte[] body = ctx.body().bytes();        // <2>
-    ...
+    // ...
   });
   
   post("/stream", ctx -> {
     InputStream body = ctx.body().stream();  // <3>
-    ...
+    // ...
   });
 }
 ----
@@ -29,57 +29,52 @@ Raw `request body` is available via javadoc:Context[body] method:
 {
   post("/string") {
     val body = ctx.body().value()   // <1>
-    ...
+    // ...
   }
   
   post("/bytes") {
     val body = ctx.body().bytes()   // <2>
-    ...
+    // ...
   }
   
   post("/stream") {
     val body = ctx.body().stream()  // <3>
-    ...
+    // ...
   }
 }
 ----
 
-<1> `HTTP Body` as `String`
-<2> `HTTP Body` as `byte array`
-<3> `HTTP Body` as `InputStream`
+<1> Reads the HTTP body as a `String`.
+<2> Reads the HTTP body as a `byte array`.
+<3> Reads the HTTP body as an `InputStream`.
 
-This gives us the `raw body`.
+===== Message Decoder
 
-==== Message Decoder
-
-Request body parsing is achieved using the javadoc:MessageDecoder[] functional interface.
+Request body parsing (converting the raw body into a specific object) is handled by the javadoc:MessageDecoder[] functional interface.
 
 [source, java]
 ----
 public interface MessageDecoder {
-
   <T> T decode(Context ctx, Type type) throws Exception;
 }
 ----
 
-javadoc:MessageDecoder[] has a single `decode` method that takes two input arguments: `(context, type)`
-and returns a single result of the given type.
+The javadoc:MessageDecoder[] has a single `decode` method that takes the request context and the target type, returning the parsed result.
 
-.JSON example:
+.JSON Decoder Example:
 [source, java, role="primary"]
 ----
 {
   FavoriteJson lib = new FavoriteJson();           // <1>
 
-  decoder(MediaType.json, (ctx, type) -> {          // <2>
-
+  decoder(MediaType.json, (ctx, type) -> {         // <2>
     byte[] body = ctx.body().bytes();              // <3>
-
     return lib.fromJson(body, type);               // <4>
   });
 
   post("/", ctx -> {
     MyObject myObject = ctx.body(MyObject.class);  // <5>
+    return myObject;
   });
 }
 ----
@@ -90,40 +85,37 @@ and returns a single result of the given type.
 {
   val lib = FavoriteJson()                 // <1>
 
-  decoder(MediaType.json) { ctx, type ->    // <2>
-
+  decoder(MediaType.json) { ctx, type ->   // <2>
     val body = ctx.body().bytes()          // <3>
-
     lib.fromJson(body, type)               // <4>
   }
 
   post("/") {
     val myObject = ctx.body<MyObject>()    // <5>
+    myObject
   }
 }
 ----
 
-<1> Choose your favorite `json` library
-<2> Check if the `Content-Type` header matches `application/json`
-<3> Read the body as `byte[]`
-<4> Parse the `body` and use the requested type
-<5> Route handler now call the `body(Type)` function to trigger the decoder function
+<1> Initialize your favorite JSON library.
+<2> Register the decoder to trigger when the `Content-Type` header matches `application/json`.
+<3> Read the raw body as a `byte[]`.
+<4> Parse the payload into the requested type.
+<5> Inside the route, calling `ctx.body(Type)` automatically triggers the registered decoder.
 
-=== Response Body
+==== Response Body
 
-Response body is generated from `handler` function:
+The response body is generated by the route handler.
 
-.Response body
+.Response Body Example
 [source, java,role="primary"]
 ----
 {
   get("/", ctx -> {
-    ctx.setResponseCode(200);                  // <1>
-
+    ctx.setResponseCode(200);                   // <1>
     ctx.setResponseType(MediaType.text);        // <2>
-
     ctx.setResponseHeader("Date", new Date());  // <3>
-
+    
     return "Response";                          // <4>
   });
 }
@@ -135,56 +127,46 @@ Response body is generated from `handler` function:
 {
   get("/") {
     ctx.responseCode = 200                 // <1>
-
     ctx.responseType = MediaType.text      // <2>
-
     ctx.setResponseHeader("Date", Date())  // <3>
-
+    
     "Response"                             // <4>
   }
 }
 ----
 
-<1> Set `status code` to `OK(200)`. This is the default `status code`
-<2> Set `content-type` to `text/plain`. This is the default `content-type`
-<3> Set the `date` header
-<4> Send a `Response` string to the client
+<1> Set the status code to `200 OK` (this is the default).
+<2> Set the `Content-Type` to `text/plain` (this is the default for strings).
+<3> Set a custom response header.
+<4> Return the response body to the client.
 
-==== Message Encoder
+===== Message Encoder
 
-Response encoding is achieved using the javadoc:MessageEncoder[] functional interface.
+Response encoding (converting an object into a raw HTTP response) is handled by the javadoc:MessageEncoder[] functional interface.
 
 [source, java]
 ----
 public interface MessageEncoder {
-
   Output encode(@NonNull Context ctx, @NonNull Object value) throws Exception;
 }
 ----
 
-MessageEncoder has a single `encode` method that accepts two input arguments: `(context, value)` and 
-produces a result.
+The javadoc:MessageEncoder[] has a single `encode` method that accepts the context and the value returned by the handler, producing an output. (Internally, javadoc:output.Output[] works like a `java.nio.ByteBuffer` for performance reasons).
 
-The javadoc:output.Output[] works like `java.nio.ByteBuffer` and it is used internally
-for performance reason.
-
-.JSON example:
+.JSON Encoder Example:
 [source, java, role="primary"]
 ----
 {
   FavoriteJson lib = new FavoriteJson();           // <1>
 
-  encoder(MediaType.json, (ctx, result) -> {      // <2>
-
+  encoder(MediaType.json, (ctx, result) -> {       // <2>
     String json = lib.toJson(result);              // <3>
-
     ctx.setDefaultResponseType(MediaType.json);    // <4>
-
     return json;                                   // <5>
   });
 
   get("/item", ctx -> {
-    MyObject myObject = ...;
+    MyObject myObject = new MyObject();
     return myObject;                               // <6>
   });
 }
@@ -196,25 +178,22 @@ for performance reason.
 {
   val lib = FavoriteJson()                         // <1>
 
-  encoder(MediaType.json) { ctx, result ->        // <2>
-
+  encoder(MediaType.json) { ctx, result ->         // <2>
     val json = lib.toJson(result)                  // <3>
-
     ctx.defaultResponseType = MediaType.json       // <4>
-
     json                                           // <5>
   }
 
   get("/item") {
-    val myObject = ...;
+    val myObject = MyObject()
     myObject                                       // <6>
   }
 }
 ----
 
-<1> Choose your favorite `json` library
-<2> Check if the `Accept` header matches `application/json`
-<3> Convert `result` to `JSON`
-<4> Set default `Content-Type` to `application/json`
-<5> Produces JSON response
-<6> Route handler returns a user defined type
+<1> Initialize your favorite JSON library.
+<2> Register the encoder to trigger when the client's `Accept` header matches `application/json`.
+<3> Convert the route's result into JSON.
+<4> Set the `Content-Type` header to `application/json`.
+<5> Return the encoded JSON payload.
+<6> The route handler returns a user-defined POJO, which is automatically intercepted and encoded.