Merge pull request #235 from drivasperez/main

Tweak main lib docs

Author: yoshuawuyts

src/lib.rs

@@ -21,9 +21,9 @@
 //!
 //! # How does HTTP work?
 //!
-//! We couldn't possibly explain _all_ of HTTP here, as there's [5 versions](enum.Version.html) of
-//! the protocol now, and lots of extensions. But at its core there are only a few concepts you
-//! need to know about.
+//! We couldn't possibly explain _all_ of HTTP here: there are [5 versions](enum.Version.html) of
+//! the protocol now, and lots of extensions. But, at its core, there are only a few concepts you
+//! need to know about in order to understand what this crate does.
 //!
 //! ```txt
 //!          request
@@ -39,7 +39,7 @@
 //! does some work, and sends back a [`Response`](struct.Response.html).
 //!
 //! The `Url` works as a way to subdivide an IP address/domain into further addressable resources.
-//! The `Method` indicates what kind of operation we're trying perform (get something, submit
+//! The `Method` indicates what kind of operation we're trying to perform (get something, submit
 //! something, update something, etc.)
 //!
 //! ```txt
@@ -54,9 +54,9 @@
 //! ```
 //!
 //! A `Response` consists of a [`StatusCode`](enum.StatusCode.html),
-//! [`Headers`](struct.Headers.html), and optional [`Body`](struct.Body.html). The client then
+//! [`Headers`](struct.Headers.html), and optionally a [`Body`](struct.Body.html). The client then
 //! decodes the `Response`, and can then operate on it. Usually the first thing it does is check
-//! the status code to see if it was successful or not, and then operates on the headers.
+//! the status code to see if its `Request` was successful or not, and then moves on to the information contained within the headers.
 //!
 //! ```txt
 //!      Response
@@ -72,25 +72,25 @@
 //! requests. It needs to be encoded in a specific way (all lowercase ASCII, only some special
 //! characters) so we use the [`HeaderName`](headers/struct.HeaderName.html) and
 //! [`HeaderValue`](headers/struct.HeaderValue.html) structs rather than strings to ensure that.
-//! Also another interesting thing about this is that it's valid to have multiple instances of the
-//! same header name. Which is why `Headers` allows inserting multiple values, and always returns a
-//! vector of headers for each key.
+//! Another interesting thing about this is that it's valid to have multiple instances of the
+//! same header name. This is why `Headers` allows inserting multiple values, and always returns a
+//! [`Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html) of headers for each key.
 //!
 //! When reading up on HTTP you might frequently hear a lot of jargon related to ther underlying
 //! protocols. But even newer HTTP versions (`HTTP/2`, `HTTP/3`) still fundamentally use the
 //! request/response model we've described so far.
 //!
 //! # The Body Type
 //!
-//! In HTTP [`Body`](struct.Body.html) types are optional. But funamentally they're streams of
-//! bytes with a specific encoding, also known as [`Mime` type](struct.Mime.html). The `Mime` can
+//! In HTTP, [`Body`](struct.Body.html) types are optional. The content of a `Body` is a stream of
+//! bytes with a specific encoding; this encoding is its [`Mime` type](struct.Mime.html). The `Mime` can
 //! be set using the [`set_content_type`](struct.Request.html#method.set_content_type) method, and
-//! there are many different `Mime` types possible.
+//! there are many different possible `Mime` types.
 //!
 //! `http-types`' `Body` struct can take anything that implements
 //! [`AsyncBufRead`](https://docs.rs/futures/0.3.1/futures/io/trait.AsyncBufRead.html) and stream
 //! it out. Depending on the version of HTTP used, the underlying bytes will be transmitted
-//! differently. But as a rule: if you know the size of the body, it's usually more efficient to
+//! differently. As a rule, if you know the size of the body it's usually more efficient to
 //! declare it up front. But if you don't, things will still work.
 
 #![deny(missing_debug_implementations, nonstandard_style)]