Added more docs and examples.

Author: illegalprime

src/codec/http.rs

@@ -1,3 +1,7 @@
+//! Send HTTP requests and responses asynchronously.
+//!
+//! This module has both an `HttpClientCodec` for an async HTTP client and an
+//! `HttpServerCodec` for an async HTTP server.
 use std::io::{self, Write};
 use std::error::Error;
 use std::fmt::{self, Formatter, Display};
@@ -15,6 +19,39 @@ use bytes::BytesMut;
 use bytes::BufMut;
 
 #[derive(Copy, Clone, Debug)]
+///```rust,no_run
+///# extern crate tokio_core;
+///# extern crate tokio_io;
+///# extern crate websocket;
+///# extern crate hyper;
+///# use websocket::codec::http::HttpClientCodec;
+///# use websocket::async::futures::Future;
+///# use websocket::async::futures::Sink;
+///# use tokio_core::net::TcpStream;
+///# use tokio_core::reactor::Core;
+///# use tokio_io::AsyncRead;
+///# use hyper::http::h1::Incoming;
+///# use hyper::version::HttpVersion;
+///# use hyper::header::Headers;
+///# use hyper::method::Method;
+///# use hyper::uri::RequestUri;
+///
+///# fn main() {
+///let core = Core::new().unwrap();
+///
+///let f = TcpStream::connect(&"crouton.net".parse().unwrap(), &core.handle())
+///    .and_then(|s| {
+///        Ok(s.framed(HttpClientCodec))
+///    })
+///    .and_then(|s| {
+///        s.send(Incoming {
+///            version: HttpVersion::Http11,
+///            subject: (Method::Get, RequestUri::AbsolutePath("/".to_string())),
+///            headers: Headers::new(),
+///        })
+///    });
+///# }
+///```
 pub struct HttpClientCodec;
 
 fn split_off_http(src: &mut BytesMut) -> Option<BytesMut> {

src/codec/mod.rs

@@ -1,2 +1,14 @@
+//! Useful `Codec` types for asynchronously encoding and decoding messages.
+//!
+//! This is intended to be used with the `Framed` type in the `tokio-io` crate.
+//! This module contains an `http` codec which can be used to send and receive
+//! hyper HTTP requests and responses asynchronously.
+//! See it's module level documentation for more info.
+//!
+//! Second but most importantly this module contains a codec for asynchronously
+//! encoding and decoding websocket messages (and dataframes if you want to go
+//! more low level) in the `ws` module.
+//! See it's module level documentation for more info.
+
 pub mod http;
 pub mod ws;

src/dataframe.rs

@@ -37,7 +37,10 @@ impl DataFrame {
 		}
 	}
 
-	/// TODO: docs
+	/// Take the body and header of a dataframe and combine it into a single
+	/// Dataframe struct. A websocket message can be made up of many individual
+	/// dataframes, use the methods from the Message or OwnedMessage structs to
+	/// take many of these and create a websocket message.
 	pub fn read_dataframe_body(
 		header: DataFrameHeader,
 		body: Vec<u8>,

src/lib.rs

@@ -52,7 +52,7 @@ extern crate tokio_io;
 #[cfg(feature="async")]
 extern crate bytes;
 #[cfg(feature="async")]
-extern crate futures;
+pub extern crate futures;
 #[cfg(feature="async-ssl")]
 extern crate tokio_tls;
 
@@ -147,6 +147,12 @@ pub mod async {
 	pub use client::async::Client;
 
 	pub use result::async::WebSocketFuture;
+
+	pub use futures;
+	pub use tokio_core::net::TcpStream;
+	pub use tokio_core::net::TcpListener;
+	pub use tokio_core::reactor::Core;
+	pub use tokio_core::reactor::Handle;
 }
 
 pub use self::message::Message;

src/message.rs

@@ -229,7 +229,14 @@ impl<'a> ws::Message for Message<'a> {
 	}
 }
 
-/// Represents a WebSocket message.
+/// Represents an owned WebSocket message.
+///
+/// `OwnedMessage`s are generated when the user receives a message (since the data
+/// has to be copied out of the network buffer anyway).
+/// If you would like to create a message out of borrowed data to use for sending
+/// please use the `Message` struct (which contains a `Cow`).
+///
+/// Note that `OwnedMessage` can `Message` can be converted into each other.
 #[derive(Eq, PartialEq, Clone, Debug)]
 pub enum OwnedMessage {
 	/// A message containing UTF-8 text data
@@ -249,13 +256,28 @@ pub enum OwnedMessage {
 }
 
 impl OwnedMessage {
+	/// Checks if this message is a close message.
+	///
+	///```rust
+	///# use websocket::OwnedMessage;
+	///assert!(OwnedMessage::Close(None).is_close());
+	///```
 	pub fn is_close(&self) -> bool {
 		match *self {
 			OwnedMessage::Close(_) => true,
 			_ => false,
 		}
 	}
 
+	/// Checks if this message is a control message.
+	/// Control messages are either `Close`, `Ping`, or `Pong`.
+	///
+	///```rust
+	///# use websocket::OwnedMessage;
+	///assert!(OwnedMessage::Ping(vec![]).is_control());
+	///assert!(OwnedMessage::Pong(vec![]).is_control());
+	///assert!(OwnedMessage::Close(None).is_control());
+	///```
 	pub fn is_control(&self) -> bool {
 		match *self {
 			OwnedMessage::Close(_) => true,
@@ -265,17 +287,40 @@ impl OwnedMessage {
 		}
 	}
 
+	/// Checks if this message is a data message.
+	/// Data messages are either `Text` or `Binary`.
+	///
+	///```rust
+	///# use websocket::OwnedMessage;
+	///assert!(OwnedMessage::Text("1337".to_string()).is_data());
+	///assert!(OwnedMessage::Binary(vec![]).is_data());
+	///```
 	pub fn is_data(&self) -> bool {
 		!self.is_control()
 	}
 
+	/// Checks if this message is a ping message.
+	/// `Ping` messages can come at any time and usually generate a `Pong` message
+	/// response.
+	///
+	///```rust
+	///# use websocket::OwnedMessage;
+	///assert!(OwnedMessage::Ping("ping".to_string().into_bytes()).is_ping());
+	///```
 	pub fn is_ping(&self) -> bool {
 		match *self {
 			OwnedMessage::Ping(_) => true,
 			_ => false,
 		}
 	}
 
+	/// Checks if this message is a pong message.
+	/// `Pong` messages are usually sent only in response to `Ping` messages.
+	///
+	///```rust
+	///# use websocket::OwnedMessage;
+	///assert!(OwnedMessage::Pong("pong".to_string().into_bytes()).is_pong());
+	///```
 	pub fn is_pong(&self) -> bool {
 		match *self {
 			OwnedMessage::Pong(_) => true,

src/result.rs

@@ -17,10 +17,15 @@ use native_tls::HandshakeError as TlsHandshakeError;
 /// The type used for WebSocket results
 pub type WebSocketResult<T> = Result<T, WebSocketError>;
 
+/// This module contains convenience types to make working with Futures and
+/// websocket results easier.
 #[cfg(feature="async")]
 pub mod async {
 	use futures::Future;
 	use super::WebSocketError;
+
+	/// The most common Future in this library, it is simply some result `I` or
+	/// a `WebSocketError`. This is analogous to the `WebSocketResult` type.
 	pub type WebSocketFuture<I> = Box<Future<Item = I, Error = WebSocketError>>;
 }
 

src/ws/sender.rs

@@ -9,6 +9,9 @@ use result::WebSocketResult;
 
 /// A trait for sending data frames and messages.
 pub trait Sender {
+	/// Should the messages sent be masked.
+	/// See the [RFC](https://tools.ietf.org/html/rfc6455#section-5.3)
+	/// for more detail.
 	fn is_masked(&self) -> bool;
 
 	/// Sends a single data frame using this sender.