From 38063b98736222a2dfeae194c9d187cf144ac807 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sat, 7 Apr 2018 17:00:57 +0200 Subject: [PATCH] docs(client): Minor formatting and spelling fixes in module docs --- src/client/connector.rs | 46 ++++++++++++++++++++--------------------- src/client/mod.rs | 13 ++++++------ src/client/pipeline.rs | 9 ++++---- src/client/request.rs | 34 ++++++++++++++++-------------- 4 files changed, 52 insertions(+), 50 deletions(-) diff --git a/src/client/connector.rs b/src/client/connector.rs index 2b9a5e2f..30eccd2f 100644 --- a/src/client/connector.rs +++ b/src/client/connector.rs @@ -33,8 +33,8 @@ use server::IoStream; #[derive(Debug)] -/// `Connect` type represents message that can be send to `ClientConnector` -/// with connection request. +/// `Connect` type represents a message that can be sent to +/// `ClientConnector` with a connection request. pub struct Connect { pub(crate) uri: Uri, pub(crate) wait_timeout: Duration, @@ -51,16 +51,16 @@ impl Connect { }) } - /// Connection timeout, max time to connect to remote host. - /// By default connect timeout is 1 seccond. + /// Connection timeout, i.e. max time to connect to remote host. + /// Set to 1 second by default. pub fn conn_timeout(mut self, timeout: Duration) -> Self { self.conn_timeout = timeout; self } /// If connection pool limits are enabled, wait time indicates - /// max time to wait for available connection. - /// By default wait timeout is 5 secconds. + /// max time to wait for a connection to become available. + /// Set to 5 seconds by default. pub fn wait_timeout(mut self, timeout: Duration) -> Self { self.wait_timeout = timeout; self @@ -99,11 +99,11 @@ impl Message for Pause { #[derive(Message)] pub struct Resume; -/// A set of errors that can occur during connecting to a http host +/// A set of errors that can occur while connecting to an HTTP host #[derive(Fail, Debug)] pub enum ClientConnectorError { - /// Invalid url - #[fail(display="Invalid url")] + /// Invalid URL + #[fail(display="Invalid URL")] InvalidUrl, /// SSL feature is not enabled @@ -125,14 +125,14 @@ pub enum ClientConnectorError { Connector(#[cause] ConnectorError), /// Connection took too long - #[fail(display = "Timeout out while establishing connection")] + #[fail(display = "Timeout while establishing connection")] Timeout, /// Connector has been disconnected #[fail(display = "Internal error: connector has been disconnected")] Disconnected, - /// Connection io error + /// Connection IO error #[fail(display = "{}", _0)] IoError(#[cause] io::Error), } @@ -152,8 +152,8 @@ struct Waiter { conn_timeout: Duration, } -/// `ClientConnector` type is responsible for transport layer of a client connection -/// of a client connection. +/// `ClientConnector` type is responsible for transport layer of a +/// client connection. pub struct ClientConnector { #[cfg(all(feature="alpn"))] connector: SslConnector, @@ -242,9 +242,9 @@ impl ClientConnector { #[cfg(feature="alpn")] /// Create `ClientConnector` actor with custom `SslConnector` instance. /// - /// By default `ClientConnector` uses very simple ssl configuration. - /// With `with_connector` method it is possible to use custom `SslConnector` - /// object. + /// By default `ClientConnector` uses very a simple SSL configuration. + /// With `with_connector` method it is possible to use a custom + /// `SslConnector` object. /// /// ```rust /// # #![cfg(feature="alpn")] @@ -313,7 +313,7 @@ impl ClientConnector { /// Set total number of simultaneous connections to the same endpoint. /// - /// Endpoints are the same if they are have equal (host, port, ssl) triplet. + /// Endpoints are the same if they have equal (host, port, ssl) triplets. /// If limit is 0, the connector has no limit. The default limit size is 0. pub fn limit_per_host(mut self, limit: usize) -> Self { self.limit_per_host = limit; @@ -322,9 +322,9 @@ impl ClientConnector { /// Set keep-alive period for opened connection. /// - /// Keep-alive period is period between connection usage. - /// if deley between connection usage exceeds this period - /// connection closes. + /// Keep-alive period is the period between connection usage. If + /// the delay between repeated usages of the same connection + /// exceeds this period, the connection is closed. pub fn conn_keep_alive(mut self, dur: Duration) -> Self { self.conn_keep_alive = dur; self @@ -333,7 +333,7 @@ impl ClientConnector { /// Set max lifetime period for connection. /// /// Connection lifetime is max lifetime of any opened connection - /// until it get closed regardless of keep-alive period. + /// until it is closed regardless of keep-alive period. pub fn conn_lifetime(mut self, dur: Duration) -> Self { self.conn_lifetime = dur; self @@ -514,7 +514,7 @@ impl ClientConnector { self.install_wait_timeout(next.unwrap()); } } - + fn install_wait_timeout(&mut self, time: Instant) { if let Some(ref mut wait) = self.wait_timeout { if wait.0 < time { @@ -601,7 +601,7 @@ impl Handler for ClientConnector { if self.pool.task.borrow().is_none() { *self.pool.task.borrow_mut() = Some(current_task()); } - + let host = uri.host().unwrap().to_owned(); let port = uri.port().unwrap_or_else(|| proto.port()); let key = Key {host, port, ssl: proto.is_secure()}; diff --git a/src/client/mod.rs b/src/client/mod.rs index 8b5713a2..89b8bdea 100644 --- a/src/client/mod.rs +++ b/src/client/mod.rs @@ -1,4 +1,4 @@ -//! Http client +//! HTTP client mod connector; mod parser; mod request; @@ -22,7 +22,6 @@ use httpresponse::HttpResponse; /// Convert `SendRequestError` to a `HttpResponse` impl ResponseError for SendRequestError { - fn error_response(&self) -> HttpResponse { match *self { SendRequestError::Connector(_) => HttpResponse::BadGateway(), @@ -32,7 +31,7 @@ impl ResponseError for SendRequestError { } } -/// Create request builder for `GET` request +/// Create request builder for `GET` requests /// /// ```rust /// # extern crate actix; @@ -66,28 +65,28 @@ pub fn get>(uri: U) -> ClientRequestBuilder { builder } -/// Create request builder for `HEAD` request +/// Create request builder for `HEAD` requests pub fn head>(uri: U) -> ClientRequestBuilder { let mut builder = ClientRequest::build(); builder.method(Method::HEAD).uri(uri); builder } -/// Create request builder for `POST` request +/// Create request builder for `POST` requests pub fn post>(uri: U) -> ClientRequestBuilder { let mut builder = ClientRequest::build(); builder.method(Method::POST).uri(uri); builder } -/// Create request builder for `PUT` request +/// Create request builder for `PUT` requests pub fn put>(uri: U) -> ClientRequestBuilder { let mut builder = ClientRequest::build(); builder.method(Method::PUT).uri(uri); builder } -/// Create request builder for `DELETE` request +/// Create request builder for `DELETE` requests pub fn delete>(uri: U) -> ClientRequestBuilder { let mut builder = ClientRequest::build(); builder.method(Method::DELETE).uri(uri); diff --git a/src/client/pipeline.rs b/src/client/pipeline.rs index 7b91adb2..5581e3b3 100644 --- a/src/client/pipeline.rs +++ b/src/client/pipeline.rs @@ -22,11 +22,11 @@ use super::{Connect, Connection, ClientConnector, ClientConnectorError}; use super::HttpClientWriter; use super::{HttpResponseParser, HttpResponseParserError}; -/// A set of errors that can occur during sending request and reading response +/// A set of errors that can occur during request sending and response reading #[derive(Fail, Debug)] pub enum SendRequestError { /// Response took too long - #[fail(display = "Timeout out while waiting for response")] + #[fail(display = "Timeout while waiting for response")] Timeout, /// Failed to connect to host #[fail(display="Failed to connect to host: {}", _0)] @@ -62,7 +62,8 @@ enum State { None, } -/// `SendRequest` is a `Future` which represents asynchronous sending process. +/// `SendRequest` is a `Future` which represents an asynchronous +/// request sending process. #[must_use = "SendRequest does nothing unless polled"] pub struct SendRequest { req: ClientRequest, @@ -102,7 +103,7 @@ impl SendRequest { /// Set request timeout /// - /// Request timeout is a total time before response should be received. + /// Request timeout is the total time before a response must be received. /// Default value is 5 seconds. pub fn timeout(mut self, timeout: Duration) -> Self { self.timeout = Some(Timeout::new(timeout, Arbiter::handle()).unwrap()); diff --git a/src/client/request.rs b/src/client/request.rs index d58a323a..c3954c78 100644 --- a/src/client/request.rs +++ b/src/client/request.rs @@ -146,13 +146,13 @@ impl ClientRequest { source.into() } - /// Get the request uri + /// Get the request URI #[inline] pub fn uri(&self) -> &Uri { &self.uri } - /// Set client request uri + /// Set client request URI #[inline] pub fn set_uri(&mut self, uri: Uri) { self.uri = uri @@ -164,13 +164,13 @@ impl ClientRequest { &self.method } - /// Set http `Method` for the request + /// Set HTTP `Method` for the request #[inline] pub fn set_method(&mut self, method: Method) { self.method = method } - /// Get http version for the request + /// Get HTTP version for the request #[inline] pub fn version(&self) -> Version { self.version @@ -222,8 +222,8 @@ impl ClientRequest { pub fn write_buffer_capacity(&self) -> usize { self.buffer_capacity } - - /// Get body os this response + + /// Get body of this response #[inline] pub fn body(&self) -> &Body { &self.body @@ -234,14 +234,14 @@ impl ClientRequest { self.body = body.into(); } - /// Extract body, replace it with Empty + /// Extract body, replace it with `Empty` pub(crate) fn replace_body(&mut self, body: Body) -> Body { mem::replace(&mut self.body, body) } /// Send request /// - /// This method returns future that resolves to a ClientResponse + /// This method returns a future that resolves to a ClientResponse pub fn send(mut self) -> SendRequest { let timeout = self.timeout.take(); let send = match mem::replace(&mut self.conn, ConnectionType::Default) { @@ -281,7 +281,7 @@ pub struct ClientRequestBuilder { } impl ClientRequestBuilder { - /// Set HTTP uri of request. + /// Set HTTP URI of request. #[inline] pub fn uri>(&mut self, uri: U) -> &mut Self { match Url::parse(uri.as_ref()) { @@ -325,7 +325,7 @@ impl ClientRequestBuilder { /// Set HTTP version of this request. /// - /// By default requests's http version depends on network stream + /// By default requests's HTTP version depends on network stream #[inline] pub fn version(&mut self, version: Version) -> &mut Self { if let Some(parts) = parts(&mut self.request, &self.err) { @@ -364,7 +364,7 @@ impl ClientRequestBuilder { /// Append a header. /// - /// Header get appended to existing header. + /// Header gets appended to existing header. /// To override header use `set_header()` method. /// /// ```rust @@ -540,7 +540,7 @@ impl ClientRequestBuilder { self } - /// Send request using existing Connection + /// Send request using existing `Connection` pub fn with_connection(&mut self, conn: Connection) -> &mut Self { if let Some(parts) = parts(&mut self.request, &self.err) { parts.conn = ConnectionType::Connection(conn); @@ -548,7 +548,8 @@ impl ClientRequestBuilder { self } - /// This method calls provided closure with builder reference if value is true. + /// This method calls provided closure with builder reference if + /// value is `true`. pub fn if_true(&mut self, value: bool, f: F) -> &mut Self where F: FnOnce(&mut ClientRequestBuilder) { @@ -558,7 +559,8 @@ impl ClientRequestBuilder { self } - /// This method calls provided closure with builder reference if value is Some. + /// This method calls provided closure with builder reference if + /// value is `Some`. pub fn if_some(&mut self, value: Option, f: F) -> &mut Self where F: FnOnce(T, &mut ClientRequestBuilder) { @@ -610,7 +612,7 @@ impl ClientRequestBuilder { Ok(request) } - /// Set a json body and generate `ClientRequest` + /// Set a JSON body and generate `ClientRequest` /// /// `ClientRequestBuilder` can not be used after this call. pub fn json(&mut self, value: T) -> Result { @@ -685,7 +687,7 @@ impl fmt::Debug for ClientRequestBuilder { /// Create `ClientRequestBuilder` from `HttpRequest` /// /// It is useful for proxy requests. This implementation -/// copies all request's headers and method. +/// copies all request headers and the method. impl<'a, S: 'static> From<&'a HttpRequest> for ClientRequestBuilder { fn from(req: &'a HttpRequest) -> ClientRequestBuilder { let mut builder = ClientRequest::build();