message: docs(examples): add comments to the echo example
diff: @@ -6,19 +6,32 @@ use hyper::rt::{Future, Stream};
  use hyper::service::service_fn;
  use hyper::{Body, Method, Request, Response, Server, StatusCode};
  +/// We need to return different futures depending on the route matched,
  +/// and we can do that with an enum, such as `futures::Either`, or with
  +/// trait objects.
  +///
  +/// A boxed Future (trait object) is used as it is easier to understand
  +/// and extend with more types. Advanced users could switch to `Either`.
  type BoxFut = Box<Future<Item = Response<Body>, Error = hyper::Error> + Send>;
  +/// This is our service handler. It receives a Request, routes on its
  +/// path, and returns a Future of a Response.
  fn echo(req: Request<Body>) -> BoxFut {
  let mut response = Response::new(Body::empty());
  match (req.method(), req.uri().path()) {
  - (&Method::GET, "/") => {
  + // Serve some instructions at /
  + (Method::GET, "/") => {
  *response.body_mut() = Body::from("Try POSTing data to /echo");
  }
  - (&Method::POST, "/echo") => {
  +
  + // Simply echo the body back to the client.
  + (Method::POST, "/echo") => {
  *response.body_mut() = req.into_body();
  }
  - (&Method::POST, "/echo/uppercase") => {
  +
  + // Convert to uppercase before sending back to client.
  + (Method::POST, "/echo/uppercase") => {
  let mapping = req.into_body().map(|chunk| {
  chunk
  .iter()
  @@ -28,7 +41,14 @@ fn echo(req: Request<Body>) -> BoxFut {
  *response.body_mut() = Body::wrap_stream(mapping);
  }
  - (&Method::POST, "/echo/reversed") => {
  +
  + // Reverse the entire body before sending back to the client.
  + //
  + // Since we don't know the end yet, we can't simply stream
  + // the chunks as they arrive. So, this returns a different
  + // future, waiting on concatenating the full body, so that
  + // it can be reversed. Only then can we return a `Response`.
  + (Method::POST, "/echo/reversed") => {
  let reversed = req.into_body().concat2().map(move |chunk| {
  let body = chunk.iter().rev().cloned().collect::<Vec<u8>>();
  *response.body_mut() = Body::from(body);
  @@ -37,6 +57,8 @@ fn echo(req: Request<Body>) -> BoxFut {
  return Box::new(reversed);
  }
  +
  + // The 404 Not Found route...
  _ => {
  *response.status_mut() = StatusCode::NOT_FOUND;
  }
  @@ -52,6 +74,6 @@ fn main() {
  .serve(|| service_fn(echo))
  .map_err(|e| eprintln!("server error: {}", e));
  - println!("The magic happens on port {}", addr.port());
  + println!("Listening on http://{}", addr);
  hyper::rt::run(server);
  }
  