Response doc improvements

[jaemk]

• I couldn't think of a less contrived example for url than just asserting it hasn't been modified...
• For the headers example, I have the file operations commented out so I didn't need to pull in an extra tempdir dev dependency. You can uncomment the three file-op lines to test that they work, but I didn't want to leave that in there to be run since it's silently modifying the project directory.

Closes #115

[seanmonstar]

Thanks so much for jumping on this, @jaemk!

I left some pointers on how we can skip some network calls when running the doctests, and also some ideas I had on possible examples that may be useful. Let me know what you think!

[seanmonstar]

Thanks so much for jumping on this, @jaemk!

I left some pointers on how we can skip some network calls when running the doctests, and also some ideas I had on possible examples that may be useful. Let me know what you think!

[seanmonstar]

This will end up making the doctests make an actual network request, which is a bummer. However! This can be changed to a smaller amount of hidden code, and still show what we want.

/// # fn run() -> Result<(), Box<::std::error::Error>> {
/// let res = reqwest::get("http://httpbin.org/")?;
/// assert_eq!(res.url().as_str(), "http://httpbin.org/");
/// # }

That's all! Also, thinking about the use of checking the url of the Response, this example also could be useful to show how you can see what the final destination url was:

/// # fn run() -> Result<(), Box<::std::error::Error>> {
/// let res = reqwest::get("http://httpbin.org/redirect/1")?;
/// assert_eq!(res.url().as_str(), "http://httpbin.org/get");
/// # }

[jaemk]

Ah jeez, didn't even cross my mind to not call the run functions! I'll clean this pr up and then do another to get rid of network calls in the rest of the doc tests.

[seanmonstar]

I think we may want to not show using the bail! macro in examples, or one might assume it's a macro from reqwest.

[jaemk]

Yeah that's probably a good idea. I'll see what I can do about removing error-chain requirements/usage.

[seanmonstar]

reqwest will follow redirects in most cases. What if we show a very common thing to do: check if the code was a 404 (StatusCode::NotFound)?

If we wanted to include multiple examples, I could imagine some others too:

1. Check for resp.status() == StatusCode::Ok, println!("response is not ok") if not.
2. Make use of the is_* methods of a StatusCode, to be more flexible. if resp.status().is_success(), or if resp.status().is_server_error(), etc.
3. If someone needed to inspect for a very specific status code, like StatusCode::PayloadTooLarge (413), when trying to upload a file.

Would showing examples in that order, from most common to more niche/advanced, be useful?

[seanmonstar]

Same comment about previous main in example. If we skip using error_chain, and thus don't need the extern crate, the example can just be in a plain # fn run() -> Result<(), Box<::std::error::Error>>.

[seanmonstar]

Having just submitted a redesign of the mime crate, seeing it's current (v0.2) API still makes me sad. Checking the content-type is definitely something useful... but I do kind of wish we could keep that verbose mess out of here... (know I'm complaining about my own work, the mime crate, not your example).

[jaemk]

I haven't seen the newer api yet, but thank you!

[seanmonstar]

I've released a v0.3, which unfortunately we can't really use yet, since it'd require breaking hyper, which can't happen. It's in the new (not yet released) 0.11 of hyper.

Basically you can either compare with the mime directly, or via parts. So, either content_type.0 == mime::IMAGE_PNG, if you wanted an exact match, or with a match if you wanted to ignore parameters or something:

match (content_type.type_(), content_type.subtype()) {
    (mime::IMAGE, mime::PNG) => (),
    _ => (),
}

No more importing all the different types. But as I said, we can't change this yet, so it's more just me complaining to myself...

[jaemk]

That direct mime-type is where it's at. We'll have it one day!

[seanmonstar]

A super simple first example could be to check the ContentLength, so as to be able to properly pre-allocate a buffer for it. Probably also best to show checking for a maximum size, so people aren't blindly downloading gigabytes accidentally.

[jaemk]

I think a simpler example like checking ContentLength would be best. The clutter of matching against the mimetype is definitely a useful example, but might be better in a standalone example.

[jaemk]

Thanks for reviewing @seanmonstar! I'll get to this later tonight.

[jaemk]

docs are updated! Note, I rebased on master and inherited the failing tests
Edit: Tests should be good now

[seanmonstar]

This looks great! Thanks!