Add missing API docs

These were written without much knowledge of the actix-web internals!
Please review carefully!

src/body.rs

@@ -127,11 +127,13 @@ impl From<Box<ActorHttpContext>> for Body {
 
 impl Binary {
     #[inline]
+    /// Returns `true` if body is empty
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
     #[inline]
+    /// Length of body in bytes
     pub fn len(&self) -> usize {
         match *self {
             Binary::Bytes(ref bytes) => bytes.len(),

src/client/connector.rs

@@ -31,11 +31,17 @@ use {HAS_OPENSSL, HAS_TLS};
 /// Client connector usage stats
 #[derive(Default, Message)]
 pub struct ClientConnectorStats {
+    /// Number of waited-on connections
     pub waits: usize,
+    /// Number of reused connections
     pub reused: usize,
+    /// Number of opened connections
     pub opened: usize,
+    /// Number of closed connections
     pub closed: usize,
+    /// Number of connections with errors
     pub errors: usize,
+    /// Number of connection timeouts
     pub timeouts: usize,
 }
 
@@ -1059,6 +1065,7 @@ impl Drop for AcquiredConn {
     }
 }
 
+/// HTTP client connection
 pub struct Connection {
     key: Key,
     stream: Box<IoStream + Send>,
@@ -1082,20 +1089,24 @@ impl Connection {
         }
     }
 
+    /// Raw IO stream
     pub fn stream(&mut self) -> &mut IoStream {
         &mut *self.stream
     }
 
+    /// Create a new connection from an IO Stream
     pub fn from_stream<T: IoStream + Send>(io: T) -> Connection {
         Connection::new(Key::empty(), None, Box::new(io))
     }
 
+    /// Close connection pool
     pub fn close(mut self) {
         if let Some(mut pool) = self.pool.take() {
             pool.close(self)
         }
     }
 
+    /// Release this connection from the connection pool
     pub fn release(mut self) {
         if let Some(mut pool) = self.pool.take() {
             pool.release(self)

src/context.rs

@@ -102,9 +102,12 @@ where
     A: Actor<Context = Self>,
 {
     #[inline]
+    /// Create a new HTTP Context from a request and an actor
     pub fn new(req: HttpRequest<S>, actor: A) -> HttpContext<A, S> {
         HttpContext::from_request(req).actor(actor)
     }
+
+    /// Create a new HTTP Context from a request
     pub fn from_request(req: HttpRequest<S>) -> HttpContext<A, S> {
         HttpContext {
             inner: ContextImpl::new(None),
@@ -113,7 +116,9 @@ where
             disconnected: false,
         }
     }
+
     #[inline]
+    /// Set the actor of this context
     pub fn actor(mut self, actor: A) -> HttpContext<A, S> {
         self.inner.set_actor(actor);
         self
@@ -239,12 +244,14 @@ where
     }
 }
 
+/// Consume a future
 pub struct Drain<A> {
     fut: oneshot::Receiver<()>,
     _a: PhantomData<A>,
 }
 
 impl<A> Drain<A> {
+    /// Create a drain from a future
     pub fn new(fut: oneshot::Receiver<()>) -> Self {
         Drain {
             fut,

src/error.rs

@@ -521,12 +521,16 @@ impl ResponseError for UriSegmentError {
 /// Errors which can occur when attempting to generate resource uri.
 #[derive(Fail, Debug, PartialEq)]
 pub enum UrlGenerationError {
+    /// Resource not found
     #[fail(display = "Resource not found")]
     ResourceNotFound,
+    /// Not all path pattern covered
     #[fail(display = "Not all path pattern covered")]
     NotEnoughElements,
+    /// Router is not available
     #[fail(display = "Router is not available")]
     RouterNotAvailable,
+    /// URL parse error
     #[fail(display = "{}", _0)]
     ParseError(#[cause] UrlParseError),
 }

src/fs.rs

@@ -422,15 +422,19 @@ type DirectoryRenderer<S> =
 /// A directory; responds with the generated directory listing.
 #[derive(Debug)]
 pub struct Directory {
+    /// Base directory
     pub base: PathBuf,
+    /// Path of subdirectory to generate listing for
     pub path: PathBuf,
 }
 
 impl Directory {
+    /// Create a new directory
     pub fn new(base: PathBuf, path: PathBuf) -> Directory {
         Directory { base, path }
     }
 
+    /// Is this entry visible from this directory?
     pub fn is_visible(&self, entry: &io::Result<DirEntry>) -> bool {
         if let Ok(ref entry) = *entry {
             if let Some(name) = entry.file_name().to_str() {

src/handler.rs

@@ -162,6 +162,7 @@ where
 /// # fn main() {}
 /// ```
 pub trait AsyncResponder<I, E>: Sized {
+    /// Convert to a boxed future
     fn responder(self) -> Box<Future<Item = I, Error = E>>;
 }
 

src/header/common/date.rs

@@ -35,6 +35,7 @@ header! {
 }
 
 impl Date {
+    /// Create a date instance set to the current system time
     pub fn now() -> Date {
         Date(SystemTime::now().into())
     }

src/header/mod.rs

@@ -127,6 +127,7 @@ pub enum ContentEncoding {
 
 impl ContentEncoding {
     #[inline]
+    /// Is the content compressed?
     pub fn is_compression(&self) -> bool {
         match *self {
             ContentEncoding::Identity | ContentEncoding::Auto => false,
@@ -135,6 +136,7 @@ impl ContentEncoding {
     }
 
     #[inline]
+    /// Convert content encoding to string
     pub fn as_str(&self) -> &'static str {
         match *self {
             #[cfg(feature = "brotli")]

src/httpcodes.rs

@@ -5,7 +5,7 @@ use httpresponse::{HttpResponse, HttpResponseBuilder};
 
 macro_rules! STATIC_RESP {
     ($name:ident, $status:expr) => {
-        #[allow(non_snake_case)]
+        #[allow(non_snake_case, missing_docs)]
         pub fn $name() -> HttpResponseBuilder {
             HttpResponse::build($status)
         }

src/httpmessage.rs

@@ -341,6 +341,7 @@ pub struct UrlEncoded<T, U> {
 }
 
 impl<T, U> UrlEncoded<T, U> {
+    /// Create a new future to URL encode a request
     pub fn new(req: T) -> UrlEncoded<T, U> {
         UrlEncoded {
             req: Some(req),

src/lib.rs

@@ -256,6 +256,7 @@ pub mod http {
 
     pub use helpers::NormalizePath;
 
+    /// Various http headers
     pub mod header {
         pub use header::*;
     }

src/middleware/cors.rs

@@ -207,6 +207,7 @@ impl Default for Cors {
 }
 
 impl Cors {
+    /// Build a new CORS middleware instance
     pub fn build() -> CorsBuilder<()> {
         CorsBuilder {
             cors: Some(Inner {

src/middleware/identity.rs

@@ -121,10 +121,15 @@ impl<S> RequestIdentity for HttpRequest<S> {
 
 /// An identity
 pub trait Identity: 'static {
+    /// Return the claimed identity of the user associated request or
+    /// ``None`` if no identity can be found associated with the request.
     fn identity(&self) -> Option<&str>;
 
+    /// Remember identity.
     fn remember(&mut self, key: String);
 
+    /// This method is used to 'forget' the current identity on subsequent
+    /// requests.
     fn forget(&mut self);
 
     /// Write session to storage backend.
@@ -133,7 +138,10 @@ pub trait Identity: 'static {
 
 /// Identity policy definition.
 pub trait IdentityPolicy<S>: Sized + 'static {
+    /// The associated identity
     type Identity: Identity;
+
+    /// The return type of the middleware
     type Future: Future<Item = Self::Identity, Error = Error>;
 
     /// Parse the session from request and load data from a service identity.

src/middleware/session.rs

@@ -103,6 +103,7 @@ use middleware::{Middleware, Response, Started};
 /// # fn main() {}
 /// ```
 pub trait RequestSession {
+    /// Get the session from the request
     fn session(&self) -> Session;
 }
 

src/multipart.rs

@@ -399,10 +399,12 @@ where
         }
     }
 
+    /// Get a map of headers
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get the content type of the field
     pub fn content_type(&self) -> &mime::Mime {
         &self.ct
     }

src/router.rs

@@ -251,6 +251,7 @@ impl Resource {
         &self.pattern
     }
 
+    /// Is this path a match against this resource?
     pub fn is_match(&self, path: &str) -> bool {
         match self.tp {
             PatternType::Static(ref s) => s == path,
@@ -259,6 +260,7 @@ impl Resource {
         }
     }
 
+    /// Are the given path and parameters a match against this resource?
     pub fn match_with_params<'a>(
         &'a self, path: &'a str, params: &'a mut Params<'a>,
     ) -> bool {
@@ -284,6 +286,7 @@ impl Resource {
         }
     }
 
+    /// Is the given path a prefix match and do the parameters match against this resource?
     pub fn match_prefix_with_params<'a>(
         &'a self, path: &'a str, params: &'a mut Params<'a>,
     ) -> Option<usize> {

src/scope.rs

@@ -63,6 +63,8 @@ pub struct Scope<S: 'static> {
 
 #[cfg_attr(feature = "cargo-clippy", allow(new_without_default_derive))]
 impl<S: 'static> Scope<S> {
+    /// Create a new scope
+    // TODO: Why is this not exactly the default impl?
     pub fn new() -> Scope<S> {
         Scope {
             filters: Vec::new(),

src/server/mod.rs

@@ -111,6 +111,7 @@ pub struct ResumeServer;
 ///
 /// If server starts with `spawn()` method, then spawned thread get terminated.
 pub struct StopServer {
+    /// Whether to try and shut down gracefully
     pub graceful: bool,
 }
 

src/server/srv.rs

@@ -686,7 +686,7 @@ where
 {
     type Result = ();
 
-    fn handle(&mut self, msg: Conn<T>, _: &mut Context<Self>) -> Self::Result {
+    fn handle(&mut self, _msg: Conn<T>, _: &mut Context<Self>) -> Self::Result {
         unimplemented!();
         /*Arbiter::spawn(HttpChannel::new(
             Rc::clone(self.h.as_ref().unwrap()),

src/test.rs

@@ -249,6 +249,7 @@ pub struct TestServerBuilder<S> {
 }
 
 impl<S: 'static> TestServerBuilder<S> {
+    /// Create a new test server
     pub fn new<F>(state: F) -> TestServerBuilder<S>
     where
         F: Fn() -> S + Sync + Send + 'static,

src/ws/client.rs

@@ -34,32 +34,46 @@ use super::{Message, ProtocolError, WsWriter};
 /// Websocket client error
 #[derive(Fail, Debug)]
 pub enum ClientError {
+    /// Invalid url
     #[fail(display = "Invalid url")]
     InvalidUrl,
+    /// Invalid response status
     #[fail(display = "Invalid response status")]
     InvalidResponseStatus(StatusCode),
+    /// Invalid upgrade header
     #[fail(display = "Invalid upgrade header")]
     InvalidUpgradeHeader,
+    /// Invalid connection header
     #[fail(display = "Invalid connection header")]
     InvalidConnectionHeader(HeaderValue),
+    /// Missing CONNECTION header
     #[fail(display = "Missing CONNECTION header")]
     MissingConnectionHeader,
+    /// Missing SEC-WEBSOCKET-ACCEPT header
     #[fail(display = "Missing SEC-WEBSOCKET-ACCEPT header")]
     MissingWebSocketAcceptHeader,
+    /// Invalid challenge response
     #[fail(display = "Invalid challenge response")]
     InvalidChallengeResponse(String, HeaderValue),
+    /// Http parsing error
     #[fail(display = "Http parsing error")]
     Http(Error),
+    /// Url parsing error
     #[fail(display = "Url parsing error")]
     Url(UrlParseError),
+    /// Response parsing error
     #[fail(display = "Response parsing error")]
     ResponseParseError(HttpResponseParserError),
+    /// Send request error
     #[fail(display = "{}", _0)]
     SendRequest(SendRequestError),
+    /// Protocol error
     #[fail(display = "{}", _0)]
     Protocol(#[cause] ProtocolError),
+    /// IO Error
     #[fail(display = "{}", _0)]
     Io(io::Error),
+    /// "Disconnected"
     #[fail(display = "Disconnected")]
     Disconnected,
 }
@@ -419,6 +433,7 @@ impl Future for ClientHandshake {
     }
 }
 
+/// Websocket reader client
 pub struct ClientReader {
     inner: Rc<UnsafeCell<Inner>>,
     max_size: usize,
@@ -497,6 +512,7 @@ impl Stream for ClientReader {
     }
 }
 
+/// Websocket writer client
 pub struct ClientWriter {
     inner: Rc<UnsafeCell<Inner>>,
 }

src/ws/context.rs

@@ -86,10 +86,12 @@ where
     A: Actor<Context = Self>,
 {
     #[inline]
+    /// Create a new Websocket context from a request and an actor
     pub fn new(req: HttpRequest<S>, actor: A) -> WebsocketContext<A, S> {
         WebsocketContext::from_request(req).actor(actor)
     }
 
+    /// Create a new Websocket context from a request
     pub fn from_request(req: HttpRequest<S>) -> WebsocketContext<A, S> {
         WebsocketContext {
             inner: ContextImpl::new(None),
@@ -100,6 +102,7 @@ where
     }
 
     #[inline]
+    /// Set actor for this execution context
     pub fn actor(mut self, actor: A) -> WebsocketContext<A, S> {
         self.inner.set_actor(actor);
         self

src/ws/mod.rs

@@ -158,10 +158,15 @@ impl ResponseError for HandshakeError {
 /// `WebSocket` Message
 #[derive(Debug, PartialEq, Message)]
 pub enum Message {
+    /// Text message
     Text(String),
+    /// Binary message
     Binary(Binary),
+    /// Ping message
     Ping(String),
+    /// Pong message
     Pong(String),
+    /// Close message with optional reason
     Close(Option<CloseReason>),
 }
 

src/ws/proto.rs

@@ -180,8 +180,11 @@ impl From<u16> for CloseCode {
 }
 
 #[derive(Debug, Eq, PartialEq, Clone)]
+/// Reason for closing the connection
 pub struct CloseReason {
+    /// Exit code
     pub code: CloseCode,
+    /// Optional description of the exit code
     pub description: Option<String>,
 }