diff --git a/src/client.rs b/src/client.rs index 346a3c0..1ead2bb 100644 --- a/src/client.rs +++ b/src/client.rs @@ -116,6 +116,10 @@ struct Config { impl ClientBuilder { /// Constructs a new `ClientBuilder` + /// + /// # Errors + /// + /// This method fails if native TLS backend cannot be created. pub fn new() -> ::Result { let tls_connector_builder = try_!(native_tls::TlsConnector::builder()); Ok(ClientBuilder { @@ -132,10 +136,14 @@ impl ClientBuilder { /// Returns a `Client` that uses this `ClientBuilder` configuration. /// - /// # Note + /// # Errors /// - /// This consumes the internal state of the builder. Trying to use this - /// builder again after calling `build` will panic. + /// This method fails if native TLS backend cannot be initialized. + /// + /// # Panics + /// + /// This method consumes the internal state of the builder. + /// Trying to use this builder again after calling `build` will panic. pub fn build(&mut self) -> ::Result { let config = self.take_config(); @@ -170,6 +178,10 @@ impl ClientBuilder { /// /// This can be used to connect to a server that has a self-signed /// certificate for example. + /// + /// # Errors + /// + /// This method fails if adding root certificate was unsuccessful. pub fn add_root_certificate(&mut self, cert: Certificate) -> ::Result<&mut ClientBuilder> { try_!(self.config_mut().tls.add_root_certificate(cert.0)); Ok(self) @@ -246,43 +258,75 @@ impl ClientBuilder { impl Client { /// Constructs a new `Client`. + /// + /// # Errors + /// + /// This method fails if native TLS backend cannot be created or initialized. #[inline] pub fn new() -> ::Result { ClientBuilder::new()?.build() } /// Creates a `ClientBuilder` to configure a `Client`. + /// + /// # Errors + /// + /// This method fails if native TLS backend cannot be created. #[inline] pub fn builder() -> ::Result { ClientBuilder::new() } /// Convenience method to make a `GET` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn get(&self, url: U) -> ::Result { self.request(Method::Get, url) } /// Convenience method to make a `POST` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn post(&self, url: U) -> ::Result { self.request(Method::Post, url) } /// Convenience method to make a `PUT` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn put(&self, url: U) -> ::Result { self.request(Method::Put, url) } /// Convenience method to make a `PATCH` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn patch(&self, url: U) -> ::Result { self.request(Method::Patch, url) } /// Convenience method to make a `DELETE` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn delete(&self, url: U) -> ::Result { self.request(Method::Delete, url) } /// Convenience method to make a `HEAD` request to a URL. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn head(&self, url: U) -> ::Result { self.request(Method::Head, url) } @@ -291,6 +335,10 @@ impl Client { /// /// Returns a `RequestBuilder`, which will allow setting headers and /// request body before sending. + /// + /// # Errors + /// + /// This method fails whenever supplied `Url` cannot be parsed. pub fn request(&self, method: Method, url: U) -> ::Result { let url = try_!(url.into_url()); Ok(request::builder(self.clone(), Request::new(method, url))) @@ -303,6 +351,11 @@ impl Client { /// /// You should prefer to use the `RequestBuilder` and /// `RequestBuilder::send()`. + /// + /// # Errors + /// + /// This method fails if there was an error while sending request, + /// redirect loop was detected or redirect limit was exhausted. pub fn execute(&self, request: Request) -> ::Result { self.inner.execute_request(request) } diff --git a/src/lib.rs b/src/lib.rs index 0be60a4..c5c6d56 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -208,6 +208,16 @@ mod response; /// # } /// # } /// ``` +/// +/// # Errors +/// +/// This function fails if: +/// +/// - native TLS backend cannot be initialized +/// - supplied `Url` cannot be parsed +/// - there was an error while sending request +/// - redirect loop was detected +/// - redirect limit was exhausted pub fn get(url: T) -> ::Result { Client::new()? .get(url)? diff --git a/src/request.rs b/src/request.rs index 5d8b3e6..0cb7781 100644 --- a/src/request.rs +++ b/src/request.rs @@ -153,6 +153,11 @@ impl RequestBuilder { /// # Ok(()) /// # } /// ``` + /// + /// # Errors + /// + /// This method fails if the passed value cannot be serialized into + /// url encoded format pub fn form(&mut self, form: &T) -> ::Result<&mut RequestBuilder> { { // check request_mut() before running serde @@ -202,6 +207,11 @@ impl RequestBuilder { /// Build a `Request`, which can be inspected, modified and executed with /// `Client::execute()`. + /// + /// # Panics + /// + /// This method consumes builder internal state. It panics on an attempt to + /// reuse already consumed builder. pub fn build(&mut self) -> Request { self.request .take() @@ -209,6 +219,11 @@ impl RequestBuilder { } /// Constructs the Request and sends it the target URL, returning a Response. + /// + /// # Errors + /// + /// This method fails if there was an error while sending request, + /// redirect loop was detected or redirect limit was exhausted. pub fn send(&mut self) -> ::Result<::Response> { let request = self.build(); self.client.execute(request) diff --git a/src/response.rs b/src/response.rs index cf3d3ea..8848ca9 100644 --- a/src/response.rs +++ b/src/response.rs @@ -100,6 +100,13 @@ impl Response { /// # } /// # } /// ``` + /// + /// # Errors + /// + /// This method fails whenever the response body is not in JSON format + /// or it cannot be properly deserialized to target type `T`. For more + /// details please see [`serde_json::from_reader`]. + /// [`serde_json::from_reader`]: https://docs.serde.rs/serde_json/fn.from_reader.html #[inline] pub fn json(&mut self) -> ::Result { serde_json::from_reader(self).map_err(::error::from)