From 890a7e70d68a86fddbd2b44ddc37184204d67393 Mon Sep 17 00:00:00 2001 From: Pascal Hertleif Date: Sat, 2 Jun 2018 15:51:58 +0200 Subject: [PATCH] Add missing API docs These were written without much knowledge of the actix-web internals! Please review carefully! --- src/body.rs | 2 ++ src/client/connector.rs | 11 +++++++++++ src/context.rs | 7 +++++++ src/error.rs | 4 ++++ src/fs.rs | 4 ++++ src/handler.rs | 1 + src/header/common/date.rs | 1 + src/header/mod.rs | 2 ++ src/httpcodes.rs | 2 +- src/httpmessage.rs | 1 + src/lib.rs | 1 + src/middleware/cors.rs | 1 + src/middleware/identity.rs | 8 ++++++++ src/middleware/session.rs | 1 + src/multipart.rs | 2 ++ src/router.rs | 3 +++ src/scope.rs | 2 ++ src/server/mod.rs | 1 + src/server/srv.rs | 2 +- src/test.rs | 1 + src/ws/client.rs | 16 ++++++++++++++++ src/ws/context.rs | 3 +++ src/ws/mod.rs | 5 +++++ src/ws/proto.rs | 3 +++ 24 files changed, 82 insertions(+), 2 deletions(-) diff --git a/src/body.rs b/src/body.rs index 3838d8d07..a93db1e92 100644 --- a/src/body.rs +++ b/src/body.rs @@ -127,11 +127,13 @@ impl From> 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(), diff --git a/src/client/connector.rs b/src/client/connector.rs index 36d180522..431d4df32 100644 --- a/src/client/connector.rs +++ b/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, @@ -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(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) diff --git a/src/context.rs b/src/context.rs index 3f8cf5ee3..e56c17378 100644 --- a/src/context.rs +++ b/src/context.rs @@ -102,9 +102,12 @@ where A: Actor, { #[inline] + /// Create a new HTTP Context from a request and an actor pub fn new(req: HttpRequest, actor: A) -> HttpContext { HttpContext::from_request(req).actor(actor) } + + /// Create a new HTTP Context from a request pub fn from_request(req: HttpRequest) -> HttpContext { 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 { self.inner.set_actor(actor); self @@ -239,12 +244,14 @@ where } } +/// Consume a future pub struct Drain { fut: oneshot::Receiver<()>, _a: PhantomData, } impl Drain { + /// Create a drain from a future pub fn new(fut: oneshot::Receiver<()>) -> Self { Drain { fut, diff --git a/src/error.rs b/src/error.rs index a4c513fb3..481cf3268 100644 --- a/src/error.rs +++ b/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), } diff --git a/src/fs.rs b/src/fs.rs index 8a3621072..a4418bce3 100644 --- a/src/fs.rs +++ b/src/fs.rs @@ -422,15 +422,19 @@ type DirectoryRenderer = /// 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) -> bool { if let Ok(ref entry) = *entry { if let Some(name) = entry.file_name().to_str() { diff --git a/src/handler.rs b/src/handler.rs index bae50937d..8b550059d 100644 --- a/src/handler.rs +++ b/src/handler.rs @@ -162,6 +162,7 @@ where /// # fn main() {} /// ``` pub trait AsyncResponder: Sized { + /// Convert to a boxed future fn responder(self) -> Box>; } diff --git a/src/header/common/date.rs b/src/header/common/date.rs index d130f0646..88a47bc3f 100644 --- a/src/header/common/date.rs +++ b/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()) } diff --git a/src/header/mod.rs b/src/header/mod.rs index 6b98d324a..a9c42e29c 100644 --- a/src/header/mod.rs +++ b/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")] diff --git a/src/httpcodes.rs b/src/httpcodes.rs index 2933cf175..41e57d1ee 100644 --- a/src/httpcodes.rs +++ b/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) } diff --git a/src/httpmessage.rs b/src/httpmessage.rs index 83994e343..1e57d3867 100644 --- a/src/httpmessage.rs +++ b/src/httpmessage.rs @@ -341,6 +341,7 @@ pub struct UrlEncoded { } impl UrlEncoded { + /// Create a new future to URL encode a request pub fn new(req: T) -> UrlEncoded { UrlEncoded { req: Some(req), diff --git a/src/lib.rs b/src/lib.rs index a1b61105e..88c6bd4c0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -256,6 +256,7 @@ pub mod http { pub use helpers::NormalizePath; + /// Various http headers pub mod header { pub use header::*; } diff --git a/src/middleware/cors.rs b/src/middleware/cors.rs index 93c8aeb56..b9f99f722 100644 --- a/src/middleware/cors.rs +++ b/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 { diff --git a/src/middleware/identity.rs b/src/middleware/identity.rs index c8505d686..c77f2c1c6 100644 --- a/src/middleware/identity.rs +++ b/src/middleware/identity.rs @@ -121,10 +121,15 @@ impl RequestIdentity for HttpRequest { /// 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: Sized + 'static { + /// The associated identity type Identity: Identity; + + /// The return type of the middleware type Future: Future; /// Parse the session from request and load data from a service identity. diff --git a/src/middleware/session.rs b/src/middleware/session.rs index bfc40dd5d..1e8686c05 100644 --- a/src/middleware/session.rs +++ b/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; } diff --git a/src/multipart.rs b/src/multipart.rs index 106961aec..37244d801 100644 --- a/src/multipart.rs +++ b/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 } diff --git a/src/router.rs b/src/router.rs index 81a78e577..f65e31559 100644 --- a/src/router.rs +++ b/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 { diff --git a/src/scope.rs b/src/scope.rs index 9452191f5..c103f2f87 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -63,6 +63,8 @@ pub struct Scope { #[cfg_attr(feature = "cargo-clippy", allow(new_without_default_derive))] impl Scope { + /// Create a new scope + // TODO: Why is this not exactly the default impl? pub fn new() -> Scope { Scope { filters: Vec::new(), diff --git a/src/server/mod.rs b/src/server/mod.rs index cdfebab5d..8a3f03641 100644 --- a/src/server/mod.rs +++ b/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, } diff --git a/src/server/srv.rs b/src/server/srv.rs index 665babd78..24874f153 100644 --- a/src/server/srv.rs +++ b/src/server/srv.rs @@ -686,7 +686,7 @@ where { type Result = (); - fn handle(&mut self, msg: Conn, _: &mut Context) -> Self::Result { + fn handle(&mut self, _msg: Conn, _: &mut Context) -> Self::Result { unimplemented!(); /*Arbiter::spawn(HttpChannel::new( Rc::clone(self.h.as_ref().unwrap()), diff --git a/src/test.rs b/src/test.rs index ced447f58..d8fd57733 100644 --- a/src/test.rs +++ b/src/test.rs @@ -249,6 +249,7 @@ pub struct TestServerBuilder { } impl TestServerBuilder { + /// Create a new test server pub fn new(state: F) -> TestServerBuilder where F: Fn() -> S + Sync + Send + 'static, diff --git a/src/ws/client.rs b/src/ws/client.rs index f5541beb9..d1f1402ab 100644 --- a/src/ws/client.rs +++ b/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>, max_size: usize, @@ -497,6 +512,7 @@ impl Stream for ClientReader { } } +/// Websocket writer client pub struct ClientWriter { inner: Rc>, } diff --git a/src/ws/context.rs b/src/ws/context.rs index 48f37f225..9237eab4f 100644 --- a/src/ws/context.rs +++ b/src/ws/context.rs @@ -86,10 +86,12 @@ where A: Actor, { #[inline] + /// Create a new Websocket context from a request and an actor pub fn new(req: HttpRequest, actor: A) -> WebsocketContext { WebsocketContext::from_request(req).actor(actor) } + /// Create a new Websocket context from a request pub fn from_request(req: HttpRequest) -> WebsocketContext { 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 { self.inner.set_actor(actor); self diff --git a/src/ws/mod.rs b/src/ws/mod.rs index 4c079dad9..558ecb515 100644 --- a/src/ws/mod.rs +++ b/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), } diff --git a/src/ws/proto.rs b/src/ws/proto.rs index 6e07ca7ed..35fbbe3ee 100644 --- a/src/ws/proto.rs +++ b/src/ws/proto.rs @@ -180,8 +180,11 @@ impl From 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, }