From 5c6536317c2c9bb6a784bedad6a8821f0f4b0c05 Mon Sep 17 00:00:00 2001
From: Sean McArthur <sean@seanmonstar.com>
Date: Wed, 29 Jan 2020 11:09:12 -0800
Subject: [PATCH] docs(examples): improve README for examples directory

---
 Cargo.toml         | 10 +++++-----
 examples/README.md | 42 ++++++++++++++++++++++++++++++------------
 2 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 796c1140..fd25af61 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -106,6 +106,11 @@ name = "echo"
 path = "examples/echo.rs"
 required-features = ["runtime", "stream"]
 
+[[example]]
+name = "gateway"
+path = "examples/gateway.rs"
+required-features = ["runtime"]
+
 [[example]]
 name = "hello"
 path = "examples/hello.rs"
@@ -126,11 +131,6 @@ name = "params"
 path = "examples/params.rs"
 required-features = ["runtime", "stream"]
 
-[[example]]
-name = "proxy"
-path = "examples/proxy.rs"
-required-features = ["runtime"]
-
 [[example]]
 name = "send_file"
 path = "examples/send_file.rs"
diff --git a/examples/README.md b/examples/README.md
index 33a7b7be..4c5ce61a 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,32 +1,50 @@
-## Examples of using hyper
+# Examples of using hyper
 
-Run examples with `cargo run --example example_name`.
+These examples show of how to do common tasks using `hyper`. You may also find the [Guides](https://hyper.rs/guides) helpful.
 
-### Available examples
+If you checkout this repository, you can run any of the examples `cargo run --example example_name`.
+
+### Dependencies
+
+Most of these examples use these dependencies:
+
+```toml
+[dependencies]
+hyper = "0.13"
+tokio = { version = "0.2", features = ["full"] }
+pretty_env_logger = "0.3"
+```
+
+## Getting Started
+
+### Clients
 
 * [`client`](client.rs) - A simple CLI http client that request the url passed in parameters and outputs the response content and details to the stdout, reading content chunk-by-chunk.
 
-* [`client_json`](client_json.rs) - A simple program that GETs some json, reads the body asynchronously,
-parses it with serde and outputs the result.
+* [`client_json`](client_json.rs) - A simple program that GETs some json, reads the body asynchronously, parses it with serde and outputs the result.
+
+### Servers
+
+* [`hello`](hello.rs) - A simple server that returns "Hello World!".
 
 * [`echo`](echo.rs) - An echo server that copies POST request's content to the response content.
 
-* [`hello`](hello.rs) - A simple server that returns "Hello World!" using a closure wrapped to provide a [`Service`](../src/service/service.rs).
+## Going Further
 
-* [`http_proxy`](http_proxy.rs) - A simple HTTP(S) proxy that handle and upgrade CONNECT request and then proxy data between client and remote server.
+* [`gateway`](gateway.rs) - A server gateway (reverse proxy) that proxies to the `hello` service above.
 
-* [`multi_server`](multi_server.rs) - A server that listens to two different ports, a different [`Service`](../src/service/service.rs) by port, spawning two [`futures`](../src/rt.rs).
+* [`http_proxy`](http_proxy.rs) - A simple HTTP(S) proxy that handle and upgrade `CONNECT` requests and then proxy data between client and remote server.
+
+* [`multi_server`](multi_server.rs) - A server that listens to two different ports, a different `Service` per port.
 
 * [`params`](params.rs) - A webserver that accept a form, with a name and a number, checks the parameters are presents and validates the input.
 
-* [`proxy`](proxy.rs) - A webserver that proxies to the hello service above.
-
 * [`send_file`](send_file.rs) - A server that sends back content of files using tokio_fs to read the files asynchronously.
 
 * [`single_threaded`](single_threaded.rs) - A server only running on 1 thread, so it can make use of `!Send` app state (like an `Rc` counter).
 
 * [`state`](state.rs) - A webserver showing basic state sharing among requests. A counter is shared, incremented for every request, and every response is sent the last count.
 
-* [`upgrades`](upgrades.rs) - A server and client demonstrating how to do HTTP upgrades (such as WebSockets or `CONNECT` tunneling).
+* [`upgrades`](upgrades.rs) - A server and client demonstrating how to do HTTP upgrades (such as WebSockets).
 
-* [`web_api`](web_api.rs) - A server consisting in a service that returns incoming POST request's content in the response in uppercase and a service that call that call the first service and includes the first service response in its own response.
+* [`web_api`](web_api.rs) - A server consisting in a service that returns incoming POST request's content in the response in uppercase and a service that calls the first service and includes the first service response in its own response.