chore: cleanup docs and warnings, strict docs

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

src/client.rs

@@ -13,6 +13,7 @@ mod encryption {
     pub use native_tls::TlsStream;
 
     pub use stream::Stream as StreamSwitcher;
+    /// TCP stream switcher (plain/TLS).
     pub type AutoStream = StreamSwitcher<TcpStream, TlsStream<TcpStream>>;
 
     use stream::Mode;
@@ -41,6 +42,7 @@ mod encryption {
     use stream::Mode;
     use error::{Error, Result};
 
+    /// TLS support is nod compiled in, this is just standard `TcpStream`.
     pub type AutoStream = TcpStream;
 
     pub fn wrap_stream(stream: TcpStream, _domain: &str, mode: Mode) -> Result<AutoStream> {
@@ -78,7 +80,7 @@ pub fn connect<'t, Req: Into<Request<'t>>>(request: Req) -> Result<WebSocket<Aut
     let mode = url_mode(&request.url)?;
     let addrs = request.url.to_socket_addrs()?;
     let mut stream = connect_to_some(addrs, &request.url, mode)?;
-    stream.set_nodelay(true)?;
+    NoDelay::set_nodelay(&mut stream, true)?;
     client(request, stream)
         .map_err(|e| match e {
             HandshakeError::Failure(f) => f,

src/error.rs

@@ -15,9 +15,11 @@ use protocol::frame::CloseFrame;
 
 #[cfg(feature="tls")]
 pub mod tls {
+    //! TLS error wrapper module, feature-gated.
     pub use native_tls::Error;
 }
 
+/// Result type of all Tungstenite library calls.
 pub type Result<T> = result::Result<T, Error>;
 
 /// Possible WebSocket errors

src/handshake/client.rs

@@ -1,3 +1,5 @@
+//! Client handshake machine.
+
 use base64;
 use rand;
 use httparse;
@@ -14,7 +16,9 @@ use super::machine::{HandshakeMachine, StageResult, TryParse};
 
 /// Client request.
 pub struct Request<'t> {
+    /// `ws://` or `wss://` URL to connect to.
     pub url: Url,
+    /// Extra HTTP headers to append to the request.
     pub extra_headers: Option<&'t [(&'t str, &'t str)]>,
 }
 

src/handshake/headers.rs

@@ -1,3 +1,5 @@
+//! HTTP Request and response header handling.
+
 use std::ascii::AsciiExt;
 use std::str::from_utf8;
 use std::slice;
@@ -8,7 +10,7 @@ use httparse::Status;
 use error::Result;
 use super::machine::TryParse;
 
-// Limit the number of header lines.
+/// Limit for the number of header lines.
 pub const MAX_HEADERS: usize = 124;
 
 /// HTTP request or response headers.
@@ -70,6 +72,7 @@ impl<'name, 'headers> Iterator for HeadersIter<'name, 'headers> {
 
 /// Trait to convert raw objects into HTTP parseables.
 pub trait FromHttparse<T>: Sized {
+    /// Convert raw object into parsed HTTP headers.
     fn from_httparse(raw: T) -> Result<Self>;
 }
 

src/handshake/server.rs

@@ -1,3 +1,5 @@
+//! Server handshake machine.
+
 use httparse;
 use httparse::Status;
 
@@ -10,7 +12,9 @@ use super::{MidHandshake, HandshakeRole, ProcessingResult, convert_key};
 
 /// Request from the client.
 pub struct Request {
+    /// Path part of the URL.
     pub path: String,
+    /// HTTP headers.
     pub headers: Headers,
 }
 

src/lib.rs

@@ -1,5 +1,6 @@
 //! Lightweight, flexible WebSockets for Rust.
 #![deny(
+    missing_docs,
     missing_copy_implementations,
     trivial_casts, trivial_numeric_casts,
     unstable_features,

src/protocol/frame/coding.rs

@@ -6,7 +6,9 @@ use std::convert::{Into, From};
 /// WebSocket message opcode as in RFC 6455.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum OpCode {
+    /// Data (text or binary).
     Data(Data),
+    /// Control message (close, ping, pong).
     Control(Control),
 }
 

src/stream.rs

@@ -14,12 +14,15 @@ use native_tls::TlsStream;
 /// Stream mode, either plain TCP or TLS.
 #[derive(Clone, Copy)]
 pub enum Mode {
+    /// Plain mode (`ws://` URL).
     Plain,
+    /// TLS mode (`wss://` URL).
     Tls,
 }
 
 /// Trait to switch TCP_NODELAY.
 pub trait NoDelay {
+    /// Set the TCP_NODELAY option to the given value.
     fn set_nodelay(&mut self, nodelay: bool) -> IoResult<()>;
 }
 
@@ -38,7 +41,9 @@ impl<S: Read + Write + NoDelay> NoDelay for TlsStream<S> {
 
 /// Stream, either plain TCP or TLS.
 pub enum Stream<S, T> {
+    /// Unencrypted socket stream.
     Plain(S),
+    /// Encrypted socket stream.
     Tls(T),
 }
 

src/util.rs

@@ -7,6 +7,7 @@ use error::Error;
 
 /// Non-blocking IO handling.
 pub trait NonBlockingError: Sized {
+    /// Convert WouldBlock to None and don't touch other errors.
     fn into_non_blocking(self) -> Option<Self>;
 }
 
@@ -29,8 +30,12 @@ impl NonBlockingError for Error {
 }
 
 /// Non-blocking IO wrapper.
+///
+/// This trait is implemented for `Result<T, E: NonBlockingError>`.
 pub trait NonBlockingResult {
+    /// Type of the converted result: `Result<Option<T>, E>`
     type Result;
+    /// Perform the non-block conversion.
     fn no_block(self) -> Self::Result;
 }