Add a README for the examples

3 files changed, 63 insertions, 1 deletions

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..2ae05b53
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,47 @@
+## Examples of `tokio-core`
+
+This directory contains a number of examples showcasing various capabilities of
+the `tokio_core` crate. Most of these examples also leverage the `futures` and
+`tokio_io` crates, along with a number of other miscellaneous dependencies for
+various tasks.
+
+All examples can be executed with:
+
+```
+cargo run --example $name
+```
+
+A high level description of each example is:
+
+* `hello` - a tiny server that simply writes "Hello!" to all connected clients
+  and then terminates the connection, should help see how to create and
+  initialize `tokio_core`.
+* `echo` - this is your standard TCP "echo server" which simply accepts
+  connections and then echos back any contents that are read from each connected
+  client.
+* `echo-udp` - again your standard "echo server", except for UDP instead of TCP.
+  This will echo back any packets received to the original sender.
+* `echo-threads` - servers the same purpose as the `echo` example, except this
+  shows off using multiple cores on a machine for doing I/O processing.
+* `connect` - this is a `nc`-like clone which can be used to interact with most
+  other examples. The program creates a TCP connection or UDP socket to sends
+  all information read on stdin to the remote peer, displaying any data received
+  on stdout. Often quite useful when interacting with the various other servers
+  here!
+* `chat` - this spins up a local TCP server which will broadcast from any
+  connected client to all other connected clients. You can connect to this in
+  multiple terminals and use it to chat between the terminals.
+* `proxy` - an example proxy server that will forward all connected TCP clients
+  to the remote address specified when starting the program.
+* `sink` - a benchmark-like example which shows writing 0s infinitely to any
+  connected client.
+* `tinyhttp` - a tiny HTTP/1.1 server which doesn't support HTTP request bodies
+  showcasing running on multiple cores, working with futures and spawning
+  tasks, and finally framing a TCP connection to discrete request/response
+  objects.
+* `udp-codec` - an example of using the `UdpCodec` trait along with a small
+  ping-pong protocol happening locally.
+
+If you've got an example you'd like to see here, please feel free to open an
+issue. Otherwise if you've got an example you'd like to add, please feel free
+to make a PR!
diff --git a/examples/echo-threads.rs b/examples/echo-threads.rs
index 1cb94e87..810fd048 100644
--- a/examples/echo-threads.rs
+++ b/examples/echo-threads.rs
@@ -7,7 +7,7 @@
 //!
 //! To see this server in action, you can run this in one terminal:
 //!
-//!     cargo run --example echoe-threads
+//!     cargo run --example echo-threads
 //!
 //! and in another terminal you can run:
 //!
diff --git a/examples/proxy.rs b/examples/proxy.rs
index 4920cc9f..7bc53819 100644
--- a/examples/proxy.rs
+++ b/examples/proxy.rs
@@ -1,5 +1,20 @@
 //! A proxy that forwards data to another server and forwards that server's
 //! responses back to clients.
+//!
+//! You can showcase this by running this in one terminal:
+//!
+//!     cargo run --example proxy
+//!
+//! This in another terminal
+//!
+//!     cargo run --example echo
+//!
+//! And finally this in another terminal
+//!
+//!     cargo run --example connect 127.0.0.1:8081
+//!
+//! This final terminal will connect to our proxy, which will in turn connect to
+//! the echo server, and you'll be able to see data flowing between them.
 
 extern crate futures;
 extern crate tokio_core;