improve docs

Author: jayjamesjay

examples/chunked.rs

@@ -1,11 +1,11 @@
 use http_req::request;
 
 fn main() {
-    //Sends a HTTP GET request and processes the response.
+    // Sends a HTTP GET request and processes the response.
     let mut body = Vec::new();
     let res = request::get("https://jigsaw.w3.org/HTTP/ChunkedScript", &mut body).unwrap();
 
-    //Prints details about the response.
+    // Prints details about the response.
     println!("Status: {} {}", res.status_code(), res.reason());
     println!("Headers: {}", res.headers());
     //println!("{}", String::from_utf8_lossy(&body));

examples/get.rs

@@ -1,10 +1,10 @@
 use http_req::request;
 
 fn main() {
-    //Container for body of a response.
+    // Container for body of a response.
     let mut body = Vec::new();
 
-    //Sends a HTTP GET request and processes the response. Saves body of the response to `body` variable.
+    // Sends a HTTP GET request and processes the response. Saves body of the response to `body` variable.
     let res = request::get("https://www.rust-lang.org/learn", &mut body).unwrap();
 
     //Prints details about the response.

examples/head.rs

@@ -1,10 +1,10 @@
 use http_req::request;
 
 fn main() {
-    //Sends a HTTP HEAD request and processes the response.
+    // Sends a HTTP HEAD request and processes the response.
     let res = request::head("https://www.rust-lang.org/learn").unwrap();
 
-    //Prints details about the response.
+    // Prints the details about the response.
     println!("Status: {} {}", res.status_code(), res.reason());
     println!("Headers: {}", res.headers());
 }

examples/post.rs

@@ -1,17 +1,17 @@
 use http_req::request;
 
 fn main() {
-    //Container for body of a response.
+    // Container for body of a response.
     let mut res_body = Vec::new();
 
-    //Body of a request.
+    // Body of a request.
     const REQ_BODY: &[u8; 27] = b"field1=value1&field2=value2";
 
-    //Sends a HTTP POST request and processes the response.
+    // Sends a HTTP POST request and processes the response.
     let res = request::post("https://httpbin.org/post", REQ_BODY, &mut res_body).unwrap();
 
-    //Prints details about the response.
+    // Prints details about the response.
     println!("Status: {} {}", res.status_code(), res.reason());
     println!("Headers: {}", res.headers());
-    println!("{}", String::from_utf8_lossy(&res_body));
+    //println!("{}", String::from_utf8_lossy(&res_body));
 }

examples/request_builder_get.rs

@@ -11,35 +11,35 @@ use std::{
 };
 
 fn main() {
-    //Parses a URI and assigns it to a variable `addr`.
+    // Parses a URI and assigns it to a variable `addr`.
     let addr: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
 
-    //Containers for a server's response.
+    // Containers for a server's response.
     let raw_head;
     let mut body = Vec::new();
 
-    //Prepares a request message.
+    // Prepares a request message.
     let request_msg = RequestBuilder::new(&addr)
         .header("Connection", "Close")
         .parse();
 
-    //Connects to a server. Uses information from `addr`.
+    // Connects to a server. Uses information from `addr`.
     let mut stream = Stream::new(&addr, Some(Duration::from_secs(60))).unwrap();
     stream = Stream::try_to_https(stream, &addr, None).unwrap();
 
-    //Makes a request to server - sends a prepared message.
+    // Makes a request to server. Sends the prepared message.
     stream.write_all(&request_msg).unwrap();
 
-    //Wraps the stream in BufReader to make it easier to read from it.
-    //Reads a response from the server and saves the head to `raw_head`, and the body to `body`.
+    // Wraps the stream in BufReader to make it easier to read from it.
+    // Reads a response from the server and saves the head to `raw_head`, and the body to `body`.
     let mut stream = BufReader::new(stream);
     raw_head = stream::read_head(&mut stream);
     stream.read_to_end(&mut body).unwrap();
 
-    //Parses and processes the response.
+    // Parses and processes the response.
     let response = Response::from_head(&raw_head).unwrap();
 
-    //Prints infromation about the response.
+    // Prints infromation about the response.
     println!("Status: {} {}", response.status_code(), response.reason());
     println!("Headers: {}", response.headers());
     //println!("{}", String::from_utf8_lossy(&body));

src/lib.rs

@@ -1,5 +1,8 @@
 //! Simple HTTP client with built-in HTTPS support.
-//! Currently it's in heavy development and may frequently change.
+//! 
+//! By default uses [rust-native-tls](https://github.com/sfackler/rust-native-tls),
+//! which relies on TLS framework provided by OS on Windows and macOS, and OpenSSL
+//! on all other platforms. But it also supports [rus-tls](https://crates.io/crates/rustls).
 //!
 //! ## Example
 //! Basic GET request

src/request.rs

@@ -26,7 +26,9 @@ pub enum Method {
     POST,
     PUT,
     DELETE,
+    CONNECT,
     OPTIONS,
+    TRACE,
     PATCH,
 }
 
@@ -40,7 +42,9 @@ impl fmt::Display for Method {
             POST => "POST",
             PUT => "PUT",
             DELETE => "DELETE",
+            CONNECT => "CONNECT",
             OPTIONS => "OPTIONS",
+            TRACE => "TRACE",
             PATCH => "PATCH",
         };
 
@@ -300,10 +304,9 @@ impl<'a> Request<'a> {
     /// use http_req::{request::Request, uri::Uri};
     /// use std::convert::TryFrom;
     ///
-    /// let mut writer = Vec::new();
     /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     ///
-    /// let response = Request::new(&uri).send(&mut writer).unwrap();;
+    /// let request = Request::new(&uri);
     /// ```
     pub fn new(uri: &'a Uri) -> Request<'a> {
         let mut builder = RequestBuilder::new(&uri);
@@ -328,7 +331,7 @@ impl<'a> Request<'a> {
     ///
     /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .method(Method::HEAD);
     /// ```
     pub fn method<T>(&mut self, method: T) -> &mut Self
@@ -348,7 +351,7 @@ impl<'a> Request<'a> {
     ///
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .version(HttpVersion::Http10);
     /// ```
 
@@ -375,7 +378,7 @@ impl<'a> Request<'a> {
     /// headers.insert("Host", "rust-lang.org");
     /// headers.insert("Connection", "Close");
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .headers(headers);
     /// ```
     pub fn headers<T>(&mut self, headers: T) -> &mut Self
@@ -395,7 +398,7 @@ impl<'a> Request<'a> {
     ///
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .header("Accept-Language", "en-US");
     /// ```
     pub fn header<T, U>(&mut self, key: &T, val: &U) -> &mut Self
@@ -417,7 +420,7 @@ impl<'a> Request<'a> {
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// const body: &[u8; 27] = b"field1=value1&field2=value2";
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .method(Method::POST)
     ///     .header("Content-Length", &body.len())
     ///     .body(body);
@@ -446,7 +449,7 @@ impl<'a> Request<'a> {
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// const time: Option<Duration> = Some(Duration::from_secs(10));
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .connect_timeout(time);
     /// ```
     pub fn connect_timeout<T>(&mut self, timeout: Option<T>) -> &mut Self
@@ -472,7 +475,7 @@ impl<'a> Request<'a> {
     /// let uri: Uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// const time: Option<Duration> = Some(Duration::from_secs(15));
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .read_timeout(time);
     /// ```
     pub fn read_timeout<T>(&mut self, timeout: Option<T>) -> &mut Self
@@ -498,7 +501,7 @@ impl<'a> Request<'a> {
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// const time: Option<Duration> = Some(Duration::from_secs(5));
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .write_timeout(time);
     /// ```
     pub fn write_timeout<T>(&mut self, timeout: Option<T>) -> &mut Self
@@ -520,7 +523,7 @@ impl<'a> Request<'a> {
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// const time: Duration = Duration::from_secs(5);
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .timeout(time);
     /// ```
     pub fn timeout<T>(&mut self, timeout: T) -> &mut Self
@@ -541,7 +544,7 @@ impl<'a> Request<'a> {
     /// let uri = Uri::try_from("https://www.rust-lang.org/learn").unwrap();
     /// let path = Path::new("./foo/bar.txt");
     ///
-    /// let response = Request::new(&uri)
+    /// let request = Request::new(&uri)
     ///     .root_cert_file_pem(&path);
     /// ```
     pub fn root_cert_file_pem(&mut self, file_path: &'a Path) -> &mut Self {

src/stream.rs

@@ -226,11 +226,14 @@ where
 /// Exexcutes a function in a loop until operation is completed or deadline is exceeded.
 ///
 /// It checks if a timeout was exceeded every iteration, therefore it limits
-/// how many time a specific function can be called before deadline.
-/// However a deadline may be exceeded if a single function call takes too much time.
-///
-/// Function `func` needs to return `true` when the operation is complete.
-///
+/// how many time a specific function can be called before deadline. 
+/// For the `execute_with_deadline` to meet the deadline, each call 
+/// to `func` needs finish before the deadline. 
+/// 
+/// Key information about function `func`:
+/// - is provided with information about remaining time
+/// - must ensure that its execution will not take more time than specified in `remaining_time`
+/// - needs to return `true` when the operation is complete
 pub fn execute_with_deadline<F>(deadline: Instant, mut func: F)
 where
     F: FnMut(Duration) -> bool,
@@ -247,8 +250,8 @@ where
 
 /// Reads the head of HTTP response from `reader`.
 ///
-/// Reads from `reader` (line by line) until a blank line is found
-/// indicating that all meta-information for the request has been sent.
+/// Reads from `reader` (line by line) until a blank line is identified, 
+/// which indicates that all meta-information has been read,
 pub fn read_head<B>(reader: &mut B) -> Vec<u8>
 where
     B: BufRead,