Merge pull request #194 from sagebind/readme-example-updates

Expand first readme example to full program

README.md

@@ -51,16 +51,28 @@ Safe Rust bindings to libcurl are provided by the [curl crate], which you can us
 
 ## [Documentation]
 
-Please check out the [documentation] for details on what Isahc can do and how to use it. To get you started, here is a really simple example that spits out the response body from https://example.org:
+Please check out the [documentation] for details on what Isahc can do and how to use it. To get you started, here is a really simple, complete example that spits out the response body from https://example.org:
 
 ```rust
-// Send a GET request and wait for the response headers.
-let mut response = isahc::get("https://example.org")?;
-// Read the response body into a string and print it to standard output.
-println!("{}", response.text()?);
+use isahc::prelude::*;
+
+fn main() -> Result<(), isahc::Error> {
+    // Send a GET request and wait for the response headers.
+    // Must be `mut` so we can read the response body.
+    let mut response = isahc::get("http://example.org")?;
+
+    // Print some basic info about the response to standard output.
+    println!("Status: {}", response.status());
+    println!("Headers: {:#?}", response.headers());
+
+    // Read the response body as text into a string and print it.
+    print!("{}", response.text()?);
+
+    Ok(())
+}
 ```
 
-Click [here](https://sagebind.github.io/isahc/isahc/) for built documentation from the latest `master` build.
+Click [here][documentation] for documentation on the latest version. You can also click [here](https://sagebind.github.io/isahc/isahc/) for built documentation from the latest unreleased `master` build.
 
 ## Installation
 

examples/client.rs

@@ -0,0 +1,28 @@
+//! Another simple example that creates a custom HTTP client instance and sends
+//! a GET request with it instead of using the default client.
+
+use isahc::{
+    config::RedirectPolicy,
+    prelude::*,
+};
+use std::{
+    io::{copy, stdout},
+    time::Duration,
+};
+
+fn main() -> Result<(), isahc::Error> {
+    // Create a custom client instance and customize a couple things different
+    // than the default settings. Check the documentation of `HttpClient` and
+    // `Configurable` for everything that can be customized.
+    let client = HttpClient::builder()
+        .timeout(Duration::from_secs(5))
+        .redirect_policy(RedirectPolicy::Follow)
+        .build()?;
+
+    let mut response = client.get("https://rust-lang.org")?;
+
+    // Copy the response body directly to stdout.
+    copy(response.body_mut(), &mut stdout())?;
+
+    Ok(())
+}

examples/http2.rs

@@ -1,5 +1,10 @@
-use isahc::config::VersionNegotiation;
-use isahc::prelude::*;
+//! This example simply demonstrates HTTP/2 support by making a request that
+//! enforces usage of HTTP/2.
+
+use isahc::{
+    config::VersionNegotiation,
+    prelude::*,
+};
 
 fn main() -> Result<(), isahc::Error> {
     let response = Request::get("https://nghttp2.org")
@@ -8,7 +13,7 @@ fn main() -> Result<(), isahc::Error> {
         .map_err(Into::into)
         .and_then(isahc::send)?;
 
-    println!("{:?}", response.headers());
+    println!("{:#?}", response.headers());
 
     Ok(())
 }

examples/json.rs

@@ -1,5 +1,11 @@
-// This example uses the json feature. As such you should enable it in your Cargo.toml
-// For example, add this line in your `[dependencies]` section : `isahc = { version ="*", features = ["json"]}`
+//! This example uses the `json` crate feature. As such you should enable it in
+//! your Cargo.toml. For example, add this line in your `[dependencies]`
+//! section:
+//!
+//! ```toml
+//! isahc = { version = "*", features = ["json"]}
+//! ```
+
 use isahc::prelude::*;
 
 #[derive(Debug, serde::Serialize)]

examples/parallel_requests.rs

@@ -2,7 +2,10 @@
 //! simultaneously with no extra cost. Concurrent requests may be made in the
 //! same thread, or from different threads as in this example.
 //!
-//! We're using Rayon here to make parallelism easy.
+//! We're using [rayon] here to make parallelism easy.
+//!
+//! [rayon]: https://github.com/rayon-rs/rayon
+
 use isahc::prelude::*;
 use rayon::prelude::*;
 use std::env;

examples/progress.rs

@@ -1,6 +1,13 @@
 //! A simple command line utility that downloads a file into the void. It
 //! demonstrates how the metrics API can be used to implement an interactive
 //! progress bar.
+//!
+//! Command line options are parsed with [structopt] and the progress bar itself
+//! rendered with [indicatif], both excellent libraries for writing command line
+//! programs!
+//!
+//! [indicatif]: https://github.com/mitsuhiko/indicatif
+//! [structopt]: https://github.com/TeXitoi/structopt
 
 use indicatif::{FormattedDuration, HumanBytes, ProgressBar, ProgressStyle};
 use isahc::prelude::*;

examples/simple.rs

@@ -1,14 +1,18 @@
+//! A very basic example program that sends a GET request and prints out the
+//! response from the server.
+
 use isahc::prelude::*;
 
 fn main() -> Result<(), isahc::Error> {
-    let client = HttpClient::new()?;
-    let mut response = client.get("http://example.org")?;
+    // Send a GET request and wait for the response headers.
+    // Must be `mut` so we can read the response body.
+    let mut response = isahc::get("http://example.org")?;
 
+    // Print some basic info about the response to standard output.
     println!("Status: {}", response.status());
-    println!("Headers:\n{:?}", response.headers());
+    println!("Headers: {:#?}", response.headers());
 
-    // Copy the response body directly to stdout.
-    // std::io::copy(response.body_mut(), &mut std::io::stdout())?;
+    // Read the response body as text into a string and print it.
     print!("{}", response.text()?);
 
     Ok(())

src/lib.rs

@@ -65,9 +65,9 @@
 //! # Ok::<(), isahc::Error>(())
 //! ```
 //!
-//! Check out the
+//! For even more examples used in complete programs, please check out the
 //! [examples](https://github.com/sagebind/isahc/tree/master/examples) directory
-//! in the project sources for even more examples.
+//! in the project repo.
 //!
 //! # Feature tour
 //!