Async server use needs more documentation

Hello,

I'm moderately experienced with Rust and trying to get an async websocket server to run using this crate. I'm really having a hard time wrapping my head around this, and there's no documentation for this other than a single far too simplistic example and the reference documentation that's nearly unreadable due to all of the async stuff using types that go all over the place. The error messages I get from rustc are larger than my screen and remind me of my heavily templated C++ past.

For example, even the most basic thing of sending a text message via the websocket is not really explained anywhere.

What I found out about the example code is this:

stream.take_while(|m| Ok(!m.is_close()))

This is like the beginning of an async while loop.

.filter_map(|m| {

Receive one message from the websocket, and optionally transform the object to something else (why?).

match m {
    OwnedMessage::Ping(p) => Some(OwnedMessage::Pong(p)),
    OwnedMessage::Pong(_) => None,
    _ => Some(m),
}

Convert ping to pong, pong to not sending anything and pass along anything else. I don't see anything here actually sending a message, though. This just generates packets.

.forward(sink)

This I assume is the end of the while loop (I'm not 100% sure, that's just a hunch). I have no idea where that OwnedMessage goes to that's generated in the previous async block. It also doesn't explain how to send a message that's not a direct response to a message on the websocket.

.and_then(|(_, sink)| {sink.send(OwnedMessage::Close(None))})

When the take_while/forward-loop is done, close the socket.

I can't believe I'm the only one who has problems wrapping his head around this undocumented code. I've also been unable to find any source code online that's using this crate to create an async websocket server, which might be related to this issue.

Could you please write up some documentation and maybe even write a more thorough example? A simple chat server for example, where you can send and receive messages in a group chat.

Start with examples/async-server.rs and trace the take_while, filter_map, forward, and and_then chain described in the issue. Document how messages flow and how to send messages that are not direct responses, then add a more thorough example such as a simple group chat server.