Improve documentation.

Signed-off-by: Alexey Galakhov <agalakhov@snapview.de>

Cargo.toml

@@ -6,6 +6,8 @@ keywords = ["websocket", "io", "web"]
 authors = ["Alexey Galakhov"]
 license = "MIT"
 readme = "README.md"
+homepage = "https://github.com/snapview/tungstenite-rs"
+documentation = "https://docs.rs/tungstenite"
 repository = "https://github.com/snapview/tungstenite-rs"
 version = "0.1.1"
 

src/client.rs

@@ -1,3 +1,5 @@
+//! Methods to connect to an WebSocket as a client.
+
 use std::net::{TcpStream, SocketAddr, ToSocketAddrs};
 use std::result::Result as StdResult;
 use std::io::{Read, Write};
@@ -25,6 +27,14 @@ pub type AutoStream = TcpStream;
 ///
 /// The URL may be either ws:// or wss://.
 /// To support wss:// URLs, feature "tls" must be turned on.
+///
+/// This function "just works" for those who wants a simple blocking solution
+/// similar to `std::net::TcpStream`. If you want a non-blocking or other
+/// custom stream, call `client` instead.
+///
+/// This function uses `native_tls` to do TLS. If you want to use other TLS libraries,
+/// use `client` instead. There is no need to enable the "tls" feature if you don't call
+/// `connect` since it's the only function that uses native_tls.
 pub fn connect(url: Url) -> Result<WebSocket<AutoStream>> {
     let mode = url_mode(&url)?;
     let addrs = url.to_socket_addrs()?;
@@ -77,7 +87,8 @@ fn connect_to_some<A>(addrs: A, url: &Url, mode: Mode) -> Result<AutoStream>
 
 /// Get the mode of the given URL.
 ///
-/// This function may be used in non-blocking implementations.
+/// This function may be used to ease the creation of custom TLS streams
+/// in non-blocking algorithmss or for use with TLS libraries other than `native_tls`.
 pub fn url_mode(url: &Url) -> Result<Mode> {
     match url.scheme() {
         "ws" => Ok(Mode::Plain),
@@ -88,7 +99,9 @@ pub fn url_mode(url: &Url) -> Result<Mode> {
 
 /// Do the client handshake over the given stream.
 ///
-/// Use this function if you need a nonblocking handshake support.
+/// Use this function if you need a nonblocking handshake support or if you
+/// want to use a custom stream like `mio::tcp::TcpStream` or `openssl::ssl::SslStream`.
+/// Any stream supporting `Read + Write` will do.
 pub fn client<Stream: Read + Write>(url: Url, stream: Stream)
     -> StdResult<WebSocket<Stream>, HandshakeError<Stream, ClientHandshake>>
 {

src/handshake/mod.rs

@@ -1,3 +1,5 @@
+//! WebSocket handshake control.
+
 pub mod headers;
 pub mod client;
 pub mod server;

src/protocol/frame/coding.rs

@@ -1,3 +1,5 @@
+//! Various codes defined in RFC 6455.
+
 use std::fmt;
 use std::convert::{Into, From};
 

src/protocol/frame/mod.rs

@@ -1,3 +1,5 @@
+//! Utilities to work with raw WebSocket frames.
+
 pub mod coding;
 
 mod frame;

src/protocol/mod.rs

@@ -1,4 +1,4 @@
-//! Generic WebSocket protocol implementation
+//! Generic WebSocket message stream.
 
 pub mod frame;
 
@@ -25,7 +25,10 @@ pub enum Role {
     Client,
 }
 
-/// WebSocket input-output stream
+/// WebSocket input-output stream.
+///
+/// This is THE structure you want to create to me able to talk the WebSocket protocol.
+/// It may be created by calling `connect`, `accept` or `client` functions.
 pub struct WebSocket<Stream> {
     /// Server or client?
     role: Role,

src/server.rs

@@ -1,3 +1,5 @@
+//! Methods to accept an incoming WebSocket connection on a server.
+
 pub use handshake::server::ServerHandshake;
 
 use handshake::HandshakeError;
@@ -5,7 +7,12 @@ use protocol::WebSocket;
 
 use std::io::{Read, Write};
 
-/// Accept the given TcpStream as a WebSocket.
+/// Accept the given Stream as a WebSocket.
+///
+/// This function starts a server WebSocket handshake over the given stream.
+/// If you want TLS support, use `native_tls::TlsStream` or `openssl::ssl::SslStream`
+/// for the stream here. Any `Read + Write` streams are supported, including
+/// those from `Mio` and others.
 pub fn accept<Stream: Read + Write>(stream: Stream)
     -> Result<WebSocket<Stream>, HandshakeError<Stream, ServerHandshake>>
 {

src/stream.rs

@@ -1,3 +1,9 @@
+//! Convenience wrapper for streams to switch between plain TCP and TLS at runtime.
+//!
+//!  There is no dependency on actual TLS implementations. Everything like
+//! `native_tls` or `openssl` will work as long as there is a TLS stream supporting standard
+//! `Read + Write` traits.
+
 use std::io::{Read, Write, Result as IoResult};
 
 /// Stream mode, either plain TCP or TLS.

src/util.rs

@@ -1,3 +1,5 @@
+//! Helper traits to ease non-blocking handling.
+
 use std::io::{Error as IoError, ErrorKind as IoErrorKind};
 use std::result::Result as StdResult;