docs and doc tests

Author: illegalprime

src/client/builder.rs

@@ -15,7 +15,7 @@ use ws::receiver::Receiver as ReceiverTrait;
 use result::WebSocketResult;
 use stream::{AsTcpStream, Stream, Splittable, Shutdown};
 use dataframe::DataFrame;
-use header::{WebSocketProtocol, WebSocketExtensions, Origin};
+use header::{WebSocketProtocol, WebSocketExtensions};
 use header::extensions::Extension;
 
 use ws::dataframe::DataFrame as DataFrameable;
@@ -29,27 +29,28 @@ pub use self::builder::{ClientBuilder, Url, ParseError};
 
 /// Represents a WebSocket client, which can send and receive messages/data frames.
 ///
-/// `D` is the data frame type, `S` is the type implementing `Sender<D>` and `R`
-/// is the type implementing `Receiver<D>`.
+/// The client just wraps around a `Stream` (which is something that can be read from
+/// and written to) and handles the websocket protocol. TCP or SSL over TCP is common,
+/// but any stream can be used.
 ///
-/// For most cases, the data frame type will be `dataframe::DataFrame`, the Sender
-/// type will be `client::Sender<stream::WebSocketStream>` and the receiver type
-/// will be `client::Receiver<stream::WebSocketStream>`.
-///
-/// A `Client` can be split into a `Sender` and a `Receiver` which can then be moved
+/// A `Client` can also be split into a `Reader` and a `Writer` which can then be moved
 /// to different threads, often using a send loop and receiver loop concurrently,
 /// as shown in the client example in `examples/client.rs`.
+/// This is only possible for streams that implement the `Splittable` trait, which
+/// currently is only TCP streams. (it is unsafe to duplicate an SSL stream)
 ///
-///#Connecting to a Server
+///# Connecting to a Server
 ///
 ///```no_run
 ///extern crate websocket;
 ///# fn main() {
 ///
 ///use websocket::{ClientBuilder, Message};
 ///
-///let mut client = ClientBuilder::new("ws://127.0.0.1:1234").unwrap()
-///                     .connect(None).unwrap();
+///let mut client = ClientBuilder::new("ws://127.0.0.1:1234")
+///    .unwrap()
+///    .connect_insecure()
+///    .unwrap();
 ///
 ///let message = Message::text("Hello, World!");
 ///client.send_message(&message).unwrap(); // Send message
@@ -87,17 +88,20 @@ impl<S> Client<S>
 		self.stream.get_ref().as_tcp().shutdown(Shutdown::Both)
 	}
 
-	/// See `TcpStream.peer_addr()`.
+	/// See [`TcpStream::peer_addr`]
+	/// (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.peer_addr).
 	pub fn peer_addr(&self) -> IoResult<SocketAddr> {
 		self.stream.get_ref().as_tcp().peer_addr()
 	}
 
-	/// See `TcpStream.local_addr()`.
+	/// See [`TcpStream::local_addr`]
+	/// (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.local_addr).
 	pub fn local_addr(&self) -> IoResult<SocketAddr> {
 		self.stream.get_ref().as_tcp().local_addr()
 	}
 
-	/// See `TcpStream.set_nodelay()`.
+	/// See [`TcpStream::set_nodelay`]
+	/// (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.set_nodelay).
 	pub fn set_nodelay(&mut self, nodelay: bool) -> IoResult<()> {
 		self.stream.get_ref().as_tcp().set_nodelay(nodelay)
 	}
@@ -115,6 +119,7 @@ impl<S> Client<S>
 	/// **without sending any handshake** this is meant to only be used with
 	/// a stream that has a websocket connection already set up.
 	/// If in doubt, don't use this!
+	#[doc(hidden)]
 	pub fn unchecked(stream: BufReader<S>, headers: Headers) -> Self {
 		Client {
 			headers: headers,
@@ -159,40 +164,122 @@ impl<S> Client<S>
 		self.receiver.recv_message(&mut self.stream)
 	}
 
+	/// Access the headers that were sent in the server's handshake response.
+	/// This is a catch all for headers other than protocols and extensions.
 	pub fn headers(&self) -> &Headers {
 		&self.headers
 	}
 
+	/// **If you supplied a protocol, you must check that it was accepted by
+	/// the server** using this function.
+	/// This is not done automatically because the terms of accepting a protocol
+	/// can get complicated, especially if some protocols depend on others, etc.
+	///
+	/// ```rust,no_run
+	/// # use websocket::ClientBuilder;
+	/// let mut client = ClientBuilder::new("wss://test.fysh.in").unwrap()
+	///     .add_protocol("xmpp")
+	///     .connect_insecure()
+	///     .unwrap();
+	///
+	/// // be sure to check the protocol is there!
+	/// assert!(client.protocols().iter().any(|p| p as &str == "xmpp"));
+	/// ```
 	pub fn protocols(&self) -> &[String] {
 		self.headers
 		    .get::<WebSocketProtocol>()
 		    .map(|p| p.0.as_slice())
 		    .unwrap_or(&[])
 	}
 
+	/// If you supplied a protocol, be sure to check if it was accepted by the
+	/// server here. Since no extensions are implemented out of the box yet, using
+	/// one will require its own implementation.
 	pub fn extensions(&self) -> &[Extension] {
 		self.headers
 		    .get::<WebSocketExtensions>()
 		    .map(|e| e.0.as_slice())
 		    .unwrap_or(&[])
 	}
 
-	pub fn origin(&self) -> Option<&str> {
-		self.headers.get::<Origin>().map(|o| &o.0 as &str)
-	}
-
+	/// Get a reference to the stream.
+	/// Useful to be able to set options on the stream.
+	///
+	/// ```rust,no_run
+	/// # use websocket::ClientBuilder;
+	/// let mut client = ClientBuilder::new("ws://double.down").unwrap()
+	///     .connect_insecure()
+	///     .unwrap();
+	///
+	/// client.stream_ref().set_ttl(60).unwrap();
+	/// ```
 	pub fn stream_ref(&self) -> &S {
 		self.stream.get_ref()
 	}
 
+	/// Get a handle to the writable portion of this stream.
+	/// This can be used to write custom extensions.
+	///
+	/// ```rust,no_run
+	/// # use websocket::ClientBuilder;
+	/// use websocket::Message;
+	/// use websocket::ws::sender::Sender as SenderTrait;
+	/// use websocket::sender::Sender;
+	///
+	/// let mut client = ClientBuilder::new("ws://the.room").unwrap()
+	///     .connect_insecure()
+	///     .unwrap();
+	///
+	/// let message = Message::text("Oh hi, Mark.");
+	/// let mut sender = Sender::new(true);
+	/// let mut buf = Vec::new();
+	///
+	/// sender.send_message(&mut buf, &message);
+	///
+	/// /* transform buf somehow */
+	///
+	/// client.writer_mut().write_all(&buf);
+	/// ```
 	pub fn writer_mut(&mut self) -> &mut Write {
 		self.stream.get_mut()
 	}
 
+	/// Get a handle to the readable portion of this stream.
+	/// This can be used to transform raw bytes before they
+	/// are read in.
+	///
+	/// ```rust,no_run
+	/// # use websocket::ClientBuilder;
+	/// use std::io::Cursor;
+	/// use websocket::Message;
+	/// use websocket::ws::receiver::Receiver as ReceiverTrait;
+	/// use websocket::receiver::Receiver;
+	///
+	/// let mut client = ClientBuilder::new("ws://the.room").unwrap()
+	///     .connect_insecure()
+	///     .unwrap();
+	///
+	/// let mut receiver = Receiver::new(false);
+	/// let mut buf = Vec::new();
+	///
+	/// client.reader_mut().read_to_end(&mut buf);
+	///
+	/// /* transform buf somehow */
+	///
+	/// let mut buf_reader = Cursor::new(&mut buf);
+	/// let message: Message = receiver.recv_message(&mut buf_reader).unwrap();
+	/// ```
 	pub fn reader_mut(&mut self) -> &mut Read {
 		&mut self.stream
 	}
 
+	/// Deconstruct the client into its underlying stream and
+	/// maybe some of the buffer that was already read from the stream.
+	/// The client uses a buffered reader to read in messages, so some
+	/// bytes might already be read from the stream when this is called,
+	/// these buffered bytes are returned in the form
+	///
+	/// `(byte_buffer: Vec<u8>, buffer_capacity: usize, buffer_position: usize)`
 	pub fn into_stream(self) -> (S, Option<(Vec<u8>, usize, usize)>) {
 		let (stream, buf, pos, cap) = self.stream.into_parts();
 		(stream, Some((buf, pos, cap)))

src/client/mod.rs

@@ -10,6 +10,8 @@ use result::{WebSocketResult, WebSocketError};
 
 const INVALID_EXTENSION: &'static str = "Invalid Sec-WebSocket-Extensions extension name";
 
+// TODO: check if extension name is valid according to spec
+
 /// Represents a Sec-WebSocket-Extensions header
 #[derive(PartialEq, Clone, Debug)]
 pub struct WebSocketExtensions(pub Vec<Extension>);

src/header/extensions.rs

@@ -9,7 +9,7 @@ pub use self::protocol::WebSocketProtocol;
 pub use self::version::WebSocketVersion;
 pub use self::extensions::WebSocketExtensions;
 pub use self::origin::Origin;
-pub use hyper::header::Headers;
+pub use hyper::header::*;
 
 mod accept;
 mod key;

src/header/mod.rs

@@ -4,6 +4,8 @@ use hyper;
 use std::fmt;
 use std::ops::Deref;
 
+// TODO: only allow valid protocol names to be added
+
 /// Represents a Sec-WebSocket-Protocol header
 #[derive(PartialEq, Clone, Debug)]
 pub struct WebSocketProtocol(pub Vec<String>);

src/header/protocol.rs

@@ -38,7 +38,7 @@
 //! level. Their usage is explained in the module documentation.
 extern crate hyper;
 extern crate unicase;
-extern crate url;
+pub extern crate url;
 extern crate rustc_serialize as serialize;
 extern crate rand;
 extern crate byteorder;

src/lib.rs

@@ -14,10 +14,14 @@ use ws::receiver::{MessageIterator, DataFrameIterator};
 use stream::{AsTcpStream, Stream};
 pub use stream::Shutdown;
 
+/// This reader bundles an existing stream with a parsing algorithm.
+/// It is used by the client in its `.split()` function as the reading component.
 pub struct Reader<R>
 	where R: Read
 {
+	/// the stream to be read from
 	pub stream: BufReader<R>,
+	/// the parser to parse bytes into messages
 	pub receiver: Receiver,
 }
 
@@ -42,6 +46,8 @@ impl<R> Reader<R>
 		self.receiver.recv_message(&mut self.stream)
 	}
 
+	/// An iterator over incoming messsages.
+	/// This iterator will block until new messages arrive and will never halt.
 	pub fn incoming_messages<'a, M, D>(&'a mut self,)
 		-> MessageIterator<'a, Receiver, D, M, BufReader<R>>
 		where M: ws::Message<'a, D>,

src/receiver.rs

@@ -9,8 +9,14 @@ use ws;
 use ws::sender::Sender as SenderTrait;
 pub use stream::Shutdown;
 
+/// A writer that bundles a stream with a serializer to send the messages.
+/// This is used in the client's `.split()` function as the writing component.
+///
+/// It can also be useful to use a websocket connection without a handshake.
 pub struct Writer<W> {
+	/// The stream that websocket messages will be written to
 	pub stream: W,
+	/// The serializer that will be used to serialize the messages
 	pub sender: Sender,
 }
 

src/sender.rs

@@ -10,15 +10,31 @@ pub use self::upgrade::{Request, HyperIntoWsError};
 
 pub mod upgrade;
 
+/// When a sever tries to accept a connection many things can go wrong.
+///
+/// This struct is all the information that is recovered from a failed
+/// websocket handshake, in case one wants to use the connection for something
+/// else (such as HTTP).
 pub struct InvalidConnection<S>
 	where S: Stream
 {
+	/// if the stream was successfully setup it will be included here
+	/// on a failed connection.
 	pub stream: Option<S>,
+	/// the parsed request. **This is a normal HTTP request** meaning you can
+	/// simply run this server and handle both HTTP and Websocket connections.
+	/// If you already have a server you want to use, checkout the
+	/// `server::upgrade` module to integrate this crate with your server.
 	pub parsed: Option<Request>,
+	/// the buffered data that was already taken from the stream
 	pub buffer: Option<Buffer>,
+	/// the cause of the failed websocket connection setup
 	pub error: HyperIntoWsError,
 }
 
+/// Either the stream was established and it sent a websocket handshake
+/// which represents the `Ok` variant, or there was an error (this is the
+/// `Err` variant).
 pub type AcceptResult<S> = Result<WsUpgrade<S>, InvalidConnection<S>>;
 
 /// Marker struct for a struct not being secure
@@ -39,7 +55,7 @@ impl OptionalSslAcceptor for SslAcceptor {}
 /// This is a convenient way to implement WebSocket servers, however
 /// it is possible to use any sendable Reader and Writer to obtain
 /// a WebSocketClient, so if needed, an alternative server implementation can be used.
-///#Non-secure Servers
+///# Non-secure Servers
 ///
 /// ```no_run
 ///extern crate websocket;
@@ -63,7 +79,7 @@ impl OptionalSslAcceptor for SslAcceptor {}
 /// # }
 /// ```
 ///
-///#Secure Servers
+///# Secure Servers
 /// ```no_run
 ///extern crate websocket;
 ///extern crate openssl;
@@ -106,10 +122,21 @@ impl OptionalSslAcceptor for SslAcceptor {}
 ///}
 /// # }
 /// ```
+///
+/// # A Hyper Server
+/// This crates comes with hyper integration out of the box, you can create a hyper
+/// server and serve websocket and HTTP **on the same port!**
+/// check out the docs over at `websocket::server::upgrade::from_hyper` for an example.
+///
+/// # A Custom Server
+/// So you don't want to use any of our server implementations? That's O.K.
+/// All it takes is implementing the `IntoWs` trait for your server's streams,
+/// then calling `.into_ws()` on them.
+/// check out the docs over at `websocket::server::upgrade` for more.
 pub struct Server<S>
 	where S: OptionalSslAcceptor
 {
-	pub listener: TcpListener,
+	listener: TcpListener,
 	ssl_acceptor: S,
 }