Update documentation. (#73)

* Update documentation.

Synchronize goals section between README and rustdoc, and add two goals
(blocking API; no unsafe) that were mentioned elsewhere in the README.

Add error handling to examples for the module and for the Response
object.

And a section on synthetic errors to the top-level module documentation.

* Add back missing close brace.

* Add main function that returns Result.

* Add links to send_bytes and send_form.

* Document chunked encoding for send.

* Use a larger vec of bytes for send.

src/lib.rs

@@ -6,23 +6,33 @@
 //!
 //! * Minimal dependency tree
 //! * Obvious API
+//! * Blocking API
+//! * Convenience over correctness
+//! * No use of unsafe
 //!
 //! ```
 //! // requires feature: `ureq = { version = "*", features = ["json"] }`
 //! # #[cfg(feature = "json")] {
 //! use ureq::json;
 //!
-//! // sync post request of some json.
-//! let resp = ureq::post("https://myapi.acme.com/ingest")
-//!     .set("X-My-Header", "Secret")
-//!     .send_json(json!({
-//!         "name": "martin",
-//!         "rust": true
-//!     }));
+//! fn main() -> std::io::Result<()> {
+//!   // sync post request of some json.
+//!   let resp = ureq::post("https://myapi.example.com/ingest")
+//!       .set("X-My-Header", "Secret")
+//!       .send_json(json!({
+//!           "name": "martin",
+//!           "rust": true
+//!       }));
 //!
-//! // .ok() tells if response is 200-299.
-//! if resp.ok() {
-//!   // ....
+//!   // .ok() tells if response is 200-299.
+//!   if resp.ok() {
+//!     println!("success: {}", resp.into_string()?);
+//!   } else {
+//!     // This can include errors like failure to parse URL or connect timeout.
+//!     // They are treated as synthetic HTTP-level error statuses.
+//!     println!("error {}: {}", resp.status(), resp.into_string()?);
+//!   }
+//!   Ok(())
 //! }
 //! # }
 //! ```
@@ -37,8 +47,10 @@
 //! which follows a build pattern. The builders are finished using:
 //!
 //! * [`.call()`](struct.Request.html#method.call) without a request body.
-//! * [`.send()`](struct.Request.html#method.send) with a request body as `Read`.
+//! * [`.send()`](struct.Request.html#method.send) with a request body as `Read` (chunked encoding).
 //! * [`.send_string()`](struct.Request.html#method.send_string) body as string.
+//! * [`.send_bytes()`](struct.Request.html#method.send_bytes) body as bytes.
+//! * [`.send_form()`](struct.Request.html#method.send_form) key-value pairs as application/x-www-form-urlencoded.
 //!
 //! # JSON
 //!
@@ -91,6 +103,20 @@
 //! we first check if the user has set a `; charset=<whatwg charset>` and attempt
 //! to encode the request body using that.
 //!
+//! # Synthetic errors
+//!
+//! Rather than exposing a custom error type through results, this library has opted for
+//! representing potential connection/TLS/etc errors as HTTP response codes. These invented codes
+//! are called "[synthetic](struct.Response.html#method.synthetic)."
+//!
+//! The idea is that from a library user's point of view the distinction of whether a failure
+//! originated in the remote server (500, 502) etc, or some transient network failure, the code
+//! path of handling that would most often be the same.
+//!
+//! As a result, reading from a Response may yield an error message generated by the ureq library.
+//! To handle these errors, use the
+//! [`response.synthetic_error()`](struct.Response.html#method.synthetic_error) method.
+//!
 
 mod agent;
 mod body;