From 056803d534234b15698a5a34280d340f9446bfe9 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sun, 5 Jul 2020 01:16:53 +0100
Subject: [PATCH] revamp readme and root doc page (#1590)

---
 README.md  | 90 ++++++++++++++++++++++++++++--------------------------
 src/lib.rs | 90 +++++++++++++++++++++++++-----------------------------
 2 files changed, 87 insertions(+), 93 deletions(-)

diff --git a/README.md b/README.md
index a9b5e0116..4d6bac29c 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,58 @@
 <div align="center">
- <p><h1>Actix web</h1> </p>
-  <p><strong>Actix web is a small, pragmatic, and extremely fast rust web framework</strong> </p>
+  <h1>Actix web</h1>
+  <p>
+    <strong>Actix web is a powerful, pragmatic, and extremely fast web framework for Rust</strong>
+  </p>
   <p>
 
-[![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web) 
-[![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web) 
 [![crates.io](https://meritbadge.herokuapp.com/actix-web)](https://crates.io/crates/actix-web)
-[![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Documentation](https://docs.rs/actix-web/badge.svg)](https://docs.rs/actix-web)
-[![Download](https://img.shields.io/crates/d/actix-web.svg)](https://crates.io/crates/actix-web)
 [![Version](https://img.shields.io/badge/rustc-1.41+-lightgray.svg)](https://blog.rust-lang.org/2020/02/27/Rust-1.41.1.html)
 ![License](https://img.shields.io/crates/l/actix-web.svg)
+<br />
+[![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web) 
+[![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web) 
+[![Download](https://img.shields.io/crates/d/actix-web.svg)](https://crates.io/crates/actix-web)
+[![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
   </p>
-
-  <h3>
-    <a href="https://actix.rs">Website</a>
-    <span> | </span>
-    <a href="https://gitter.im/actix/actix">Chat</a>
-    <span> | </span>
-    <a href="https://github.com/actix/examples">Examples</a>
-  </h3>
 </div>
-<br>
 
-Actix web is a simple, pragmatic and extremely fast web framework for Rust.
+## Features
 
-* Supported *HTTP/1.x* and *HTTP/2.0* protocols
+* Supports *HTTP/1.x* and *HTTP/2*
 * Streaming and pipelining
 * Keep-alive and slow requests handling
 * Client/server [WebSockets](https://actix.rs/docs/websockets/) support
 * Transparent content compression/decompression (br, gzip, deflate)
-* Configurable [request routing](https://actix.rs/docs/url-dispatch/)
+* Powerful [request routing](https://actix.rs/docs/url-dispatch/)
 * Multipart streams
 * Static assets
-* SSL support with OpenSSL or Rustls
+* SSL support using OpenSSL or Rustls
 * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
-* Includes an asynchronous [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
+* Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
 * Supports [Actix actor framework](https://github.com/actix/actix)
-* Supports Rust 1.40+
+* Runs on stable Rust 1.41+
 
-## Docs
+## Documentation
 
-* [API documentation (master)](https://actix.rs/actix-web/actix_web)
-* [API documentation (docs.rs)](https://docs.rs/actix-web)
-* [User guide](https://actix.rs)
+* [Website & User Guide](https://actix.rs)
+* [Examples Repository](https://actix.rs/actix-web/actix_web)
+* [API Documentation](https://docs.rs/actix-web)
+* [API Documentation (master branch)](https://actix.rs/actix-web/actix_web)
 
 ## Example
 
+<h2>
+  WARNING: This example is for the master branch which is currently in beta stages for v3. For
+  Actix web v2 see the <a href="https://actix.rs/docs/getting-started/">getting started guide</a>.
+</h2>
+
 Dependencies:
 
 ```toml
 [dependencies]
-actix-web = "2"
+actix-web = "3"
 ```
 
 Code:
@@ -76,37 +76,39 @@ async fn main() -> std::io::Result<()> {
 
 ### More examples
 
-* [Basics](https://github.com/actix/examples/tree/master/basics/)
-* [Stateful](https://github.com/actix/examples/tree/master/state/)
-* [Multipart streams](https://github.com/actix/examples/tree/master/multipart/)
-* [Simple websocket](https://github.com/actix/examples/tree/master/websocket/)
-* [Tera](https://github.com/actix/examples/tree/master/template_tera/)
-* [Askama](https://github.com/actix/examples/tree/master/template_askama/) templates
-* [Diesel integration](https://github.com/actix/examples/tree/master/diesel/)
-* [r2d2](https://github.com/actix/examples/tree/master/r2d2/)
-* [OpenSSL](https://github.com/actix/examples/tree/master/openssl/)
-* [Rustls](https://github.com/actix/examples/tree/master/rustls/)
-* [Tcp/Websocket chat](https://github.com/actix/examples/tree/master/websocket-chat/)
-* [Json](https://github.com/actix/examples/tree/master/json/)
+* [Basic Setup](https://github.com/actix/examples/tree/master/basics/)
+* [Application State](https://github.com/actix/examples/tree/master/state/)
+* [JSON Handling](https://github.com/actix/examples/tree/master/json/)
+* [Multipart Streams](https://github.com/actix/examples/tree/master/multipart/)
+* [Diesel Integration](https://github.com/actix/examples/tree/master/diesel/)
+* [r2d2 Integration](https://github.com/actix/examples/tree/master/r2d2/)
+* [Simple WebSocket](https://github.com/actix/examples/tree/master/websocket/)
+* [Tera Templates](https://github.com/actix/examples/tree/master/template_tera/)
+* [Askama Templates](https://github.com/actix/examples/tree/master/template_askama/)
+* [HTTPS using Rustls](https://github.com/actix/examples/tree/master/rustls/)
+* [HTTPS using OpenSSL](https://github.com/actix/examples/tree/master/openssl/)
+* [WebSocket Chat](https://github.com/actix/examples/tree/master/websocket-chat/)
 
 You may consider checking out
 [this directory](https://github.com/actix/examples/tree/master/) for more examples.
 
 ## Benchmarks
 
-* [TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19)
+One of the fastest web frameworks available according to the
+[TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19).
 
 ## License
 
 This project is licensed under either of
 
-* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
-* MIT license ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+  [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or
+  [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
 
 at your option.
 
 ## Code of Conduct
 
-Contribution to the actix-web crate is organized under the terms of the
-Contributor Covenant, the maintainer of actix-web, @fafhrd91, promises to
-intervene to uphold that code of conduct.
+Contribution to the actix-web crate is organized under the terms of the Contributor Covenant, the
+maintainers of Actix web, promises to intervene to uphold that code of conduct.
diff --git a/src/lib.rs b/src/lib.rs
index 844f952cc..eb46af664 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,79 +1,72 @@
 #![warn(rust_2018_idioms, warnings)]
 #![allow(clippy::needless_doctest_main, clippy::type_complexity)]
 
-//! Actix web is a small, pragmatic, and extremely fast web framework
-//! for Rust.
+//! Actix web is a powerful, pragmatic, and extremely fast web framework for Rust.
 //!
 //! ## Example
 //!
 //! ```rust,no_run
-//! use actix_web::{web, App, Responder, HttpServer};
+//! use actix_web::{get, web, App, HttpServer, Responder};
 //!
-//! async fn index(info: web::Path<(String, u32)>) -> impl Responder {
-//!     format!("Hello {}! id:{}", info.0, info.1)
+//! #[get("/{id}/{name}/index.html")]
+//! async fn index(info: web::Path<(u32, String)>) -> impl Responder {
+//!     format!("Hello {}! id:{}", info.1, info.0)
 //! }
 //!
 //! #[actix_web::main]
 //! async fn main() -> std::io::Result<()> {
-//!     HttpServer::new(|| App::new().service(
-//!         web::resource("/{name}/{id}/index.html").to(index))
-//!     )
+//!     HttpServer::new(|| App::new().service(index))
 //!         .bind("127.0.0.1:8080")?
 //!         .run()
 //!         .await
 //! }
 //! ```
 //!
-//! ## Documentation & community resources
+//! ## Documentation & Community Resources
 //!
-//! Besides the API documentation (which you are currently looking
-//! at!), several other resources are available:
+//! In addition to this API documentation, several other resources are available:
 //!
-//! * [User Guide](https://actix.rs/docs/)
-//! * [Chat on gitter](https://gitter.im/actix/actix)
-//! * [GitHub repository](https://github.com/actix/actix-web)
-//! * [Cargo package](https://crates.io/crates/actix-web)
+//! * [Website & User Guide](https://actix.rs/)
+//! * [Examples Repository](https://github.com/actix/examples)
+//! * [Community Chat on Gitter](https://gitter.im/actix/actix-web)
 //!
-//! To get started navigating the API documentation you may want to
-//! consider looking at the following pages:
+//! To get started navigating the API docs, you may consider looking at the following pages first:
 //!
-//! * [App](struct.App.html): This struct represents an actix-web
-//!   application and is used to configure routes and other common
-//!   settings.
+//! * [App](struct.App.html): This struct represents an Actix web application and is used to
+//!   configure routes and other common application settings.
 //!
-//! * [HttpServer](struct.HttpServer.html): This struct
-//!   represents an HTTP server instance and is used to instantiate and
-//!   configure servers.
+//! * [HttpServer](struct.HttpServer.html): This struct represents an HTTP server instance and is
+//!   used to instantiate and configure servers.
 //!
-//! * [web](web/index.html): This module
-//!   provides essential helper functions and types for application registration.
+//! * [web](web/index.html): This module provides essential types for route registration as well as
+//!   common utilities for request handlers.
 //!
-//! * [HttpRequest](struct.HttpRequest.html) and
-//!   [HttpResponse](struct.HttpResponse.html): These structs
-//!   represent HTTP requests and responses and expose various methods
-//!   for inspecting, creating and otherwise utilizing them.
+//! * [HttpRequest](struct.HttpRequest.html) and [HttpResponse](struct.HttpResponse.html): These
+//!   structs represent HTTP requests and responses and expose methods for creating, inspecting,
+//!   and otherwise utilizing them.
 //!
 //! ## Features
 //!
-//! * Supported *HTTP/1.x* and *HTTP/2.0* protocols
+//! * Supports *HTTP/1.x* and *HTTP/2*
 //! * Streaming and pipelining
 //! * Keep-alive and slow requests handling
-//! * `WebSockets` server/client
+//! * Client/server [WebSockets](https://actix.rs/docs/websockets/) support
 //! * Transparent content compression/decompression (br, gzip, deflate)
-//! * Configurable request routing
+//! * Powerful [request routing](https://actix.rs/docs/url-dispatch/)
 //! * Multipart streams
-//! * SSL support with OpenSSL or `native-tls`
-//! * Middlewares (`Logger`, `Session`, `CORS`, `DefaultHeaders`)
+//! * Static assets
+//! * SSL support using OpenSSL or Rustls
+//! * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
+//! * Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
 //! * Supports [Actix actor framework](https://github.com/actix/actix)
-//! * Supported Rust version: 1.40 or later
+//! * Runs on stable Rust 1.41+
 //!
-//! ## Package feature
+//! ## Crate Features
 //!
-//! * `client` - enables http client (default enabled)
-//! * `compress` - enables content encoding compression support (default enabled)
-//! * `openssl` - enables ssl support via `openssl` crate, supports `http/2`
-//! * `rustls` - enables ssl support via `rustls` crate, supports `http/2`
-//! * `secure-cookies` - enables secure cookies support
+//! * `compress` - content encoding compression support (enabled by default)
+//! * `openssl` - HTTPS support via `openssl` crate, supports `HTTP/2`
+//! * `rustls` - HTTPS support via `rustls` crate, supports `HTTP/2`
+//! * `secure-cookies` - secure cookies support
 
 mod app;
 mod app_service;
@@ -97,12 +90,10 @@ pub mod test;
 mod types;
 pub mod web;
 
-pub use actix_web_codegen::*;
-pub use actix_rt as rt;
-
-// re-export for convenience
 pub use actix_http::Response as HttpResponse;
 pub use actix_http::{body, cookie, http, Error, HttpMessage, ResponseError, Result};
+pub use actix_rt as rt;
+pub use actix_web_codegen::*;
 
 pub use crate::app::App;
 pub use crate::extract::FromRequest;
@@ -203,19 +194,20 @@ pub mod dev {
 }
 
 pub mod client {
-    //! An HTTP Client
+    //! Actix web async HTTP client.
     //!
     //! ```rust
     //! use actix_web::client::Client;
     //!
-    //! #[actix_rt::main]
+    //! #[actix_web::main]
     //! async fn main() {
     //!    let mut client = Client::default();
     //!
     //!    // Create request builder and send request
     //!    let response = client.get("http://www.rust-lang.org")
-    //!       .header("User-Agent", "Actix-web")
-    //!       .send().await;                      // <- Send http request
+    //!       .header("User-Agent", "actix-web/3.0")
+    //!       .send()     // <- Send request
+    //!       .await;     // <- Wait for response
     //!
     //!    println!("Response: {:?}", response);
     //! }