Repository: seanmonstar/reqwest (language: rust)

Issue:
Error doc improvements
The `url`, `get_ref`, `is_http`, `is_serialization`, and `is_redirect` methods of `reqwest::Error` could each use an example. Remember that the point of examples is not always to show how to call the method, but to show why someone would want to call the method. For instance the get_ref example may show how to use downcast_ref to check the details of the error.


Discussion / hints:

Fix patch:
diff --git a/src/error.rs b/src/error.rs
index 3a7d94c39..98edefc87 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -4,6 +4,51 @@ use std::fmt;
 use Url;
 
 /// The Errors that may occur when processing a `Request`.
+///
+/// # Examples
+///
+/// ```
+/// #[macro_use]
+/// extern crate serde_derive;
+/// extern crate reqwest;
+///
+/// #[derive(Deserialize)]
+/// struct Simple {
+///    key: String
+/// }
+/// # fn main() { }
+///
+/// fn run() {
+///    match make_request() {
+///        Err(e) => handler(e),
+///        Ok(_)  => return,
+///    }
+/// }
+/// // Response is not a json object conforming to the Simple struct
+/// fn make_request() -> Result<Simple, reqwest::Error> {
+///   reqwest::get("http://httpbin.org/ip")?.json()
+/// }
+///
+/// fn handler(e: reqwest::Error) {
+///    if e.is_http() {
+///        match e.url() {
+///            None => println!("No Url given"),
+///            Some(url) => println!("Problem making request to: {}", url),
+///        }
+///    }
+///    // Inspect the internal error and output it
+///    if e.is_serialization() {
+///       let serde_error = match e.get_ref() {
+///            None => return,
+///            Some(err) => err,
+///        };
+///        println!("problem parsing information {}", serde_error);
+///    }
+///    if e.is_redirect() {
+///        println!("server redirecting too many times or making loop");
+///    }
+/// }
+/// ```
 #[derive(Debug)]
 pub struct Error {
     kind: Kind,
@@ -15,6 +60,25 @@ pub type Result<T> = ::std::result::Result<T, Error>;
 
 impl Error {
     /// Returns a possible URL related to this error.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # fn run() {
+    /// // displays last stop of a redirect loop
+    /// let response = reqwest::get("http://site.with.redirect.loop");
+    /// match response {
+    ///   Err(e) => if e.is_redirect() {
+    ///      let final_stop = match e.url() {
+    ///          Some(url) => url,
+    ///          None      => return,
+    ///      };
+    ///      println!("Last redirect led to: {}", final_stop);
+    ///   },
+    ///   _       => return,
+    /// };
+    /// # }
+    /// ```
     #[inline]
     pub fn url(&self) -> Option<&Url> {
         self.url.as_ref()
@@ -24,6 +88,26 @@ impl Error {
     ///
     /// The `'static` bounds allows using `downcast_ref` to check the
     /// details of the error.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// // retries requests with no host on localhost
+    /// # fn run() {
+    /// let invalid_request = "http://";
+    /// let mut response = reqwest::get(invalid_request);
+    /// match response {
+    ///   Err(e) => match e.get_ref() {
+    ///     Some(internal_error) => if internal_error.description() == "empty host" {
+    ///       let valid_request = format!("{}{}",invalid_request, "localhost");
+    ///       response = reqwest::get(&valid_request);
+    ///     },
+    ///     _          => return,
+    ///   },
+    ///   _      => return,
+    /// };
+    /// # }
+    /// ```
     #[inline]
     pub fn get_ref(&self) -> Option<&(StdError + Send + Sync + 'static)> {
         match self.kind {


Test patch: