From c8d03dd8b9c02fc07f940135e58fc7646258cd0c Mon Sep 17 00:00:00 2001
From: Andrew Gauger <andygauge@gmail.com>
Date: Sun, 11 Jun 2017 09:55:12 -0700
Subject: [PATCH] Examples for Error Documentation (#144)

---
 src/error.rs | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/src/error.rs b/src/error.rs
index 3a7d94c..98edefc 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 {