From 3a27580ebe89ad7bb082bcb7bc2c1c26b2be2690 Mon Sep 17 00:00:00 2001
From: Igor Aleksanov <popzxc@yandex.ru>
Date: Wed, 9 Sep 2020 16:24:12 +0300
Subject: [PATCH] awc: improve module documentation (#1656)

Co-authored-by: Rob Ede <robjtede@icloud.com>
---
 awc/src/lib.rs | 101 +++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 86 insertions(+), 15 deletions(-)

diff --git a/awc/src/lib.rs b/awc/src/lib.rs
index a98d6767..7167dbb9 100644
--- a/awc/src/lib.rs
+++ b/awc/src/lib.rs
@@ -4,24 +4,93 @@
     clippy::borrow_interior_mutable_const,
     clippy::needless_doctest_main
 )]
-//! An HTTP Client
+
+//! `awc` is a HTTP and WebSocket client library built using the Actix ecosystem.
+//!
+//! ## Making a GET request
 //!
 //! ```rust
-//! use actix_rt::System;
-//! use awc::Client;
+//! # #[actix_rt::main]
+//! # async fn main() -> Result<(), awc::error::SendRequestError> {
+//! let mut client = awc::Client::default();
+//! let response = client.get("http://www.rust-lang.org") // <- Create request builder
+//!     .header("User-Agent", "Actix-web")
+//!     .send()                                            // <- Send http request
+//!     .await?;
 //!
-//! #[actix_rt::main]
-//! async fn main() {
-//!    let mut client = Client::default();
-//!
-//!    let response = client.get("http://www.rust-lang.org") // <- Create request builder
-//!        .header("User-Agent", "Actix-web")
-//!        .send()                             // <- Send http request
-//!        .await;
-//!
-//!     println!("Response: {:?}", response);
-//! }
+//!  println!("Response: {:?}", response);
+//! # Ok(())
+//! # }
 //! ```
+//!
+//! ## Making POST requests
+//!
+//! ### Raw body contents
+//!
+//! ```rust
+//! # #[actix_rt::main]
+//! # async fn main() -> Result<(), awc::error::SendRequestError> {
+//! let mut client = awc::Client::default();
+//! let response = client.post("http://httpbin.org/post")
+//!     .send_body("Raw body contents")
+//!     .await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ### Forms
+//!
+//! ```rust
+//! # #[actix_rt::main]
+//! # async fn main() -> Result<(), awc::error::SendRequestError> {
+//! let params = [("foo", "bar"), ("baz", "quux")];
+//!
+//! let mut client = awc::Client::default();
+//! let response = client.post("http://httpbin.org/post")
+//!     .send_form(&params)
+//!     .await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ### JSON
+//!
+//! ```rust
+//! # #[actix_rt::main]
+//! # async fn main() -> Result<(), awc::error::SendRequestError> {
+//! let request = serde_json::json!({
+//!     "lang": "rust",
+//!     "body": "json"
+//! });
+//!
+//! let mut client = awc::Client::default();
+//! let response = client.post("http://httpbin.org/post")
+//!     .send_json(&request)
+//!     .await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## WebSocket support
+//!
+//! ```
+//! # #[actix_rt::main]
+//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! use futures_util::{sink::SinkExt, stream::StreamExt};
+//! let (_resp, mut connection) = awc::Client::new()
+//!     .ws("ws://echo.websocket.org")
+//!     .connect()
+//!     .await?;
+//!
+//! connection
+//!     .send(awc::ws::Message::Text("Echo".to_string()))
+//!     .await?;
+//! let response = connection.next().await.unwrap()?;
+//! # assert_eq!(response, awc::ws::Frame::Text("Echo".as_bytes().into()));
+//! # Ok(())
+//! # }
+//! ```
+
 use std::cell::RefCell;
 use std::convert::TryFrom;
 use std::rc::Rc;
@@ -51,7 +120,9 @@ pub use self::sender::SendClientRequest;
 
 use self::connect::{Connect, ConnectorWrapper};
 
-/// An HTTP Client
+/// An asynchronous HTTP and WebSocket client.
+///
+/// ## Examples
 ///
 /// ```rust
 /// use awc::Client;