tweak compress feature docs

awc/CHANGES.md

@@ -1,16 +1,16 @@
 # Changes
 
 ## Unreleased - 2021-xx-xx
-
 ### Changed
-
 * Change compression algorithm features flags. [#2250]
 
 [#2250]: https://github.com/actix/actix-web/pull/2250
 
+
 ## 3.0.0-beta.6 - 2021-06-17
 * No significant changes since 3.0.0-beta.5.
 
+
 ## 3.0.0-beta.5 - 2021-04-17
 ### Removed
 * Deprecated methods on `ClientRequest`: `if_true`, `if_some`. [#2148]

awc/examples/client.rs

@@ -2,17 +2,19 @@ use std::error::Error as StdError;
 
 #[actix_web::main]
 async fn main() -> Result<(), Box<dyn StdError>> {
-    std::env::set_var("RUST_LOG", "actix_http=trace");
+    std::env::set_var("RUST_LOG", "client=trace,awc=trace,actix_http=trace");
     env_logger::init();
 
     let client = awc::Client::new();
 
     // Create request builder, configure request and send
-    let mut response = client
+    let request = client
         .get("https://www.rust-lang.org/")
-        .append_header(("User-Agent", "Actix-web"))
-        .send()
-        .await?;
+        .append_header(("User-Agent", "Actix-web"));
+
+    println!("Request: {:?}", request);
+
+    let mut response = request.send().await?;
 
     // server http response
     println!("Response: {:?}", response);

awc/src/lib.rs

@@ -1,7 +1,6 @@
 //! `awc` is a HTTP and WebSocket client library built on the Actix ecosystem.
 //!
-//! ## Making a GET request
-//!
+//! # Making a GET request
 //! ```no_run
 //! # #[actix_rt::main]
 //! # async fn main() -> Result<(), awc::error::SendRequestError> {
@@ -16,10 +15,8 @@
 //! # }
 //! ```
 //!
-//! ## Making POST requests
-//!
-//! ### Raw body contents
-//!
+//! # Making POST requests
+//! ## Raw body contents
 //! ```no_run
 //! # #[actix_rt::main]
 //! # async fn main() -> Result<(), awc::error::SendRequestError> {
@@ -31,8 +28,7 @@
 //! # }
 //! ```
 //!
-//! ### Forms
-//!
+//! ## Forms
 //! ```no_run
 //! # #[actix_rt::main]
 //! # async fn main() -> Result<(), awc::error::SendRequestError> {
@@ -46,8 +42,7 @@
 //! # }
 //! ```
 //!
-//! ### JSON
-//!
+//! ## JSON
 //! ```no_run
 //! # #[actix_rt::main]
 //! # async fn main() -> Result<(), awc::error::SendRequestError> {
@@ -64,8 +59,24 @@
 //! # }
 //! ```
 //!
-//! ## WebSocket support
+//! # Response Compression
+//! All [official][iana-encodings] and common content encoding codecs are supported, optionally.
 //!
+//! The `Accept-Encoding` header will automatically be populated with enabled codecs and added to
+//! outgoing requests, allowing servers to select their `Content-Encoding` accordingly.
+//!
+//! Feature flags enable these codecs according to the table below. By default, all `compress-*`
+//! features are enabled.
+//!
+//! | Feature           | Codecs        |
+//! | ----------------- | ------------- |
+//! | `compress-brotli` | brotli        |
+//! | `compress-gzip`   | gzip, deflate |
+//! | `compress-zstd`   | zstd          |
+//!
+//! [iana-encodings]: https://www.iana.org/assignments/http-parameters/http-parameters.xhtml#content-coding
+//!
+//! # WebSocket support
 //! ```no_run
 //! # #[actix_rt::main]
 //! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -128,6 +139,9 @@ pub use self::sender::SendClientRequest;
 
 /// An asynchronous HTTP and WebSocket client.
 ///
+/// You should take care to create, at most, one `Client` per thread. Otherwise, expect higher CPU
+/// and memory usage.
+///
 /// # Examples
 /// ```
 /// use awc::Client;
@@ -136,10 +150,10 @@ pub use self::sender::SendClientRequest;
 /// async fn main() {
 ///     let mut client = Client::default();
 ///
-///     let res = client.get("http://www.rust-lang.org") // <- Create request builder
-///         .insert_header(("User-Agent", "Actix-web"))
-///         .send()                             // <- Send HTTP request
-///         .await;                             // <- send request and wait for response
+///     let res = client.get("http://www.rust-lang.org")
+///         .insert_header(("User-Agent", "my-app/1.2"))
+///         .send()
+///         .await;
 ///
 ///      println!("Response: {:?}", res);
 /// }