improve general documentation

src/async_impl/client.rs

@@ -43,7 +43,8 @@ static DEFAULT_USER_AGENT: &'static str =
 /// An asynchronous `Client` to make Requests with.
 ///
 /// The Client has various configuration values to tweak, but the defaults
-/// are set to what is usually the most commonly desired value.
+/// are set to what is usually the most commonly desired value. To configure a
+/// `Client`, use `Client::builder()`.
 ///
 /// The `Client` holds a connection pool internally, so it is advised that
 /// you create one and **reuse** it.
@@ -52,7 +53,7 @@ pub struct Client {
     inner: Arc<ClientRef>,
 }
 
-/// A `ClientBuilder` can be used to create a `Client` with  custom configuration:
+/// A `ClientBuilder` can be used to create a `Client` with  custom configuration.
 pub struct ClientBuilder {
     config: Config,
 }
@@ -77,7 +78,9 @@ struct Config {
 }
 
 impl ClientBuilder {
-    /// Constructs a new `ClientBuilder`
+    /// Constructs a new `ClientBuilder`.
+    ///
+    /// This is the same as `Client::builder()`.
     pub fn new() -> ClientBuilder {
         let mut headers: HeaderMap<HeaderValue> = HeaderMap::with_capacity(2);
         headers.insert(USER_AGENT, HeaderValue::from_static(DEFAULT_USER_AGENT));
@@ -369,6 +372,8 @@ impl Client {
     }
 
     /// Creates a `ClientBuilder` to configure a `Client`.
+    ///
+    /// This is the same as `ClientBuilder::new()`.
     pub fn builder() -> ClientBuilder {
         ClientBuilder::new()
     }

src/client.rs

@@ -16,7 +16,8 @@ use {Certificate, Identity};
 /// A `Client` to make Requests with.
 ///
 /// The Client has various configuration values to tweak, but the defaults
-/// are set to what is usually the most commonly desired value.
+/// are set to what is usually the most commonly desired value. To configure a
+/// `Client`, use `Client::builder()`.
 ///
 /// The `Client` holds a connection pool internally, so it is advised that
 /// you create one and **reuse** it.
@@ -60,7 +61,9 @@ pub struct ClientBuilder {
 }
 
 impl ClientBuilder {
-    /// Constructs a new `ClientBuilder`
+    /// Constructs a new `ClientBuilder`.
+    ///
+    /// This is the same as `Client::builder()`.
     pub fn new() -> ClientBuilder {
         ClientBuilder {
             inner: async_impl::ClientBuilder::new(),
@@ -93,8 +96,9 @@ impl ClientBuilder {
 
     /// Add a custom root certificate.
     ///
-    /// This can be used to connect to a server that has a self-signed
-    /// certificate for example.
+    /// This allows connecting to a server that has a self-signed
+    /// certificate for example. This **does not** replace the existing
+    /// trusted store.
     ///
     /// # Example
     /// ```
@@ -306,6 +310,8 @@ impl Client {
     }
 
     /// Creates a `ClientBuilder` to configure a `Client`.
+    ///
+    /// This is the same as `ClientBuilder::new()`.
     pub fn builder() -> ClientBuilder {
         ClientBuilder::new()
     }

src/lib.rs

@@ -5,15 +5,16 @@
 
 //! # reqwest
 //!
-//! The `reqwest` crate provides a convenient, higher-level HTTP Client.
+//! The `reqwest` crate provides a convenient, higher-level HTTP
+//! [`Client`][client].
 //!
 //! It handles many of the things that most people just expect an HTTP client
 //! to do for them.
 //!
-//! - Uses system-native TLS
-//! - Plain bodies, JSON, urlencoded, multipart
-//! - Customizable redirect policy
-//! - Proxies
+//! - Plain bodies, [JSON](#json), [urlencoded](#forms), [multipart](multipart)
+//! - Customizable [redirect policy](#redirect-policy)
+//! - HTTP [Proxies](proxies)
+//! - Uses system-native [TLS](#tls)
 //! - Cookies (only rudimentary support, full support is TODO)
 //!
 //! The rudimentary cookie support means that the cookies need to be manually
@@ -21,10 +22,15 @@
 //! support as of now. The tracking issue for this feature is available
 //! [on GitHub][cookiejar_issue].
 //!
-//! The `reqwest::Client` is synchronous, making it a great fit for
+//! The [`reqwest::Client`][client] is synchronous, making it a great fit for
 //! applications that only require a few HTTP requests, and wish to handle
 //! them synchronously.
 //!
+//! Additional learning resources include:
+//!
+//! - [The Rust Cookbook](https://rust-lang-nursery.github.io/rust-cookbook/web/clients.html)
+//! - [Reqwest Repositiory Examples](https://github.com/seanmonstar/reqwest/tree/master/examples
+//!
 //! ## Making a GET request
 //!
 //! For a single request, you can use the [`get`][get] shortcut method.
@@ -116,6 +122,30 @@
 //! # }
 //! ```
 //!
+//! ## Redirect Policies
+//!
+//! By default, a `Client` will automatically handle HTTP redirects, detecting
+//! loops, and having a maximum redirect chain of 10 hops. To customize this
+//! behavior, a [`RedirectPolicy`][redirect] can used with a `ClientBuilder`.
+//!
+//! ## Proxies
+//!
+//! A `Client` can be configured to make use of HTTP proxies by adding
+//! [`Proxy`](Proxy)s to a `ClientBuilder`.
+//!
+//! ## TLS
+//!
+//! By default, a `Client` will make use of system-native transport layer
+//! security to connect to HTTPS destinations. This means schannel on Windows,
+//! Security-Framework on macOS, and OpenSSL on Linux.
+//!
+//! - Additional X509 certicates can be configured on a `ClientBuilder` with the
+//!   [`Certificate`](Certificate) type.
+//! - Client certificates can be add to a `ClientBuilder` with the
+//!   [`Identity`][Identity] type.
+//! - Various parts of TLS can also be configured or even disabled on the
+//!   `ClientBuilder`.
+//!
 //! ## Optional Features
 //!
 //! The following are a list of [Cargo features][cargo-features] that can be
@@ -135,6 +165,8 @@
 //! [builder]: ./struct.RequestBuilder.html
 //! [serde]: http://serde.rs
 //! [cookiejar_issue]: https://github.com/seanmonstar/reqwest/issues/14
+//! [redirect]: ./struct.RedirectPolicy.html
+//! [Proxy]: ./struct.Proxy.html
 //! [cargo-features]: https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-features-section
 
 extern crate base64;
@@ -218,9 +250,6 @@ mod wait;
 pub mod multipart;
 
 /// An 'async' implementation of the reqwest `Client`.
-///
-/// Relies on the `futures` crate, which is unstable, hence this module
-/// is **unstable**.
 pub mod async {
     pub use ::async_impl::{
         Body,

src/redirect.rs

@@ -16,6 +16,11 @@ use Url;
 ///
 /// The default value will catch redirect loops, and has a maximum of 10
 /// redirects it will follow in a chain before returning an error.
+///
+/// - `limited` can be used have the same as the default behavior, but adjust
+///   the allowed maximum redirect hops in a chain.
+/// - `none` can be used to disable all redirect behavior.
+/// - `custom` can be used to create a customized policy.
 #[derive(Debug)]
 pub struct RedirectPolicy {
     inner: Policy,