From bd9ac9673e58f0705d26e8f00e8d84f7130ba420 Mon Sep 17 00:00:00 2001 From: Alexey Galakhov Date: Tue, 23 May 2017 02:50:29 +0200 Subject: [PATCH] chore: cleanup docs and warnings, strict docs Signed-off-by: Alexey Galakhov --- src/client.rs | 4 +++- src/error.rs | 2 ++ src/handshake/client.rs | 4 ++++ src/handshake/headers.rs | 5 ++++- src/handshake/server.rs | 4 ++++ src/lib.rs | 1 + src/protocol/frame/coding.rs | 2 ++ src/stream.rs | 5 +++++ src/util.rs | 5 +++++ 9 files changed, 30 insertions(+), 2 deletions(-) diff --git a/src/client.rs b/src/client.rs index cd353f8..3274ad0 100644 --- a/src/client.rs +++ b/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>; 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 { @@ -78,7 +80,7 @@ pub fn connect<'t, Req: Into>>(request: Req) -> Result f, diff --git a/src/error.rs b/src/error.rs index 3942d6f..4b027fd 100644 --- a/src/error.rs +++ b/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 = result::Result; /// Possible WebSocket errors diff --git a/src/handshake/client.rs b/src/handshake/client.rs index 9ef8e00..ff07d37 100644 --- a/src/handshake/client.rs +++ b/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)]>, } diff --git a/src/handshake/headers.rs b/src/handshake/headers.rs index 260b578..c9e6bee 100644 --- a/src/handshake/headers.rs +++ b/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: Sized { + /// Convert raw object into parsed HTTP headers. fn from_httparse(raw: T) -> Result; } diff --git a/src/handshake/server.rs b/src/handshake/server.rs index fbd08b6..904f1dd 100644 --- a/src/handshake/server.rs +++ b/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, } diff --git a/src/lib.rs b/src/lib.rs index 60584af..824934c 100644 --- a/src/lib.rs +++ b/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, diff --git a/src/protocol/frame/coding.rs b/src/protocol/frame/coding.rs index 97f9fd0..5fde5fb 100644 --- a/src/protocol/frame/coding.rs +++ b/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), } diff --git a/src/stream.rs b/src/stream.rs index 7e8f32a..ab2c8e2 100644 --- a/src/stream.rs +++ b/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 NoDelay for TlsStream { /// Stream, either plain TCP or TLS. pub enum Stream { + /// Unencrypted socket stream. Plain(S), + /// Encrypted socket stream. Tls(T), } diff --git a/src/util.rs b/src/util.rs index 696c0a1..a784f9c 100644 --- a/src/util.rs +++ b/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; } @@ -29,8 +30,12 @@ impl NonBlockingError for Error { } /// Non-blocking IO wrapper. +/// +/// This trait is implemented for `Result`. pub trait NonBlockingResult { + /// Type of the converted result: `Result, E>` type Result; + /// Perform the non-block conversion. fn no_block(self) -> Self::Result; }