better document relationship with tokio

actix-web-codegen/src/lib.rs

@@ -152,6 +152,10 @@ method_macro!(Patch, patch);
 
 /// Marks async main function as the Actix Web system entry-point.
 ///
+/// Note that Actix Web also works under `#[tokio::main]` since version 4.0. However, this macro is
+/// still necessary for actor support (since actors use a `System`). Read more in the
+/// [`actix_web::rt`](https://docs.rs/actix-web/4/actix_web/rt) module docs.
+///
 /// # Examples
 /// ```
 /// #[actix_web::main]

actix-web/README.md

@@ -32,7 +32,7 @@
 - Static assets
 - SSL support using OpenSSL or Rustls
 - Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
-- Includes an async [HTTP client](https://docs.rs/awc/)
+- Integrates with the [`awc` HTTP client](https://docs.rs/awc/)
 - Runs on stable Rust 1.54+
 
 ## Documentation

actix-web/src/handler.rs

@@ -10,12 +10,16 @@ use crate::{
 /// The interface for request handlers.
 ///
 /// # What Is A Request Handler
-/// A request handler has three requirements:
+/// In short, a handler is just an async function that receives request-based arguments, in any
+/// order, and returns something that can be converted to a response.
+///
+/// In particular, a request handler has three requirements:
 /// 1. It is an async function (or a function/closure that returns an appropriate future);
 /// 1. The function parameters (up to 12) implement [`FromRequest`];
 /// 1. The async function (or future) resolves to a type that can be converted into an
 ///   [`HttpResponse`] (i.e., it implements the [`Responder`] trait).
 ///
+///
 /// # Compiler Errors
 /// If you get the error `the trait Handler<_> is not implemented`, then your handler does not
 /// fulfill the _first_ of the above requirements. Missing other requirements manifest as errors on

actix-web/src/lib.rs

@@ -42,28 +42,29 @@
 //!   and otherwise utilizing them.
 //!
 //! # Features
-//! * 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, zstd)
-//! * Powerful [request routing](https://actix.rs/docs/url-dispatch/)
-//! * Multipart streams
-//! * Static assets
-//! * SSL support using OpenSSL or Rustls
-//! * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
-//! * Includes an async [HTTP client](https://docs.rs/awc/)
-//! * Runs on stable Rust 1.54+
+//! - Supports HTTP/1.x and HTTP/2
+//! - Streaming and pipelining
+//! - Powerful [request routing](https://actix.rs/docs/url-dispatch/) with optional macros
+//! - Full [Tokio](https://tokio.rs) compatibility
+//! - Keep-alive and slow requests handling
+//! - Client/server [WebSockets](https://actix.rs/docs/websockets/) support
+//! - Transparent content compression/decompression (br, gzip, deflate, zstd)
+//! - Multipart streams
+//! - Static assets
+//! - SSL support using OpenSSL or Rustls
+//! - Middlewares ([Logger, Session, CORS, etc](middleware))
+//! - Integrates with the [`awc` HTTP client](https://docs.rs/awc/)
+//! - Runs on stable Rust 1.54+
 //!
 //! # Crate Features
-//! * `cookies` - cookies support (enabled by default)
-//! * `macros` - routing and runtime macros (enabled by default)
-//! * `compress-brotli` - brotli content encoding compression support (enabled by default)
-//! * `compress-gzip` - gzip and deflate content encoding compression support (enabled by default)
-//! * `compress-zstd` - zstd 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
+//! - `cookies` - cookies support (enabled by default)
+//! - `macros` - routing and runtime macros (enabled by default)
+//! - `compress-brotli` - brotli content encoding compression support (enabled by default)
+//! - `compress-gzip` - gzip and deflate content encoding compression support (enabled by default)
+//! - `compress-zstd` - zstd 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
 
 #![deny(rust_2018_idioms, nonstandard_style)]
 #![warn(future_incompatible)]

actix-web/src/rt.rs

@@ -1,9 +1,10 @@
-//! A selection of re-exports from [`actix-rt`] and [`tokio`].
+//! A selection of re-exports from [`tokio`] and [`actix-rt`].
 //!
-//! [`actix-rt`]: https://docs.rs/actix_rt
-//! [`tokio`]: https://docs.rs/tokio
+//! Actix Web runs on [Tokio], providing full[^compat] compatibility with its huge ecosystem of
+//! crates. Each of the server's workers uses a single-threaded runtime. Read more about the
+//! architecture in [`actix-rt`]'s docs.
 //!
-//! # Running Actix Web Macro-less
+//! # Running Actix Web Without Macros
 //! ```no_run
 //! use actix_web::{middleware, rt, web, App, HttpRequest, HttpServer};
 //!
@@ -12,19 +13,53 @@
 //!     "Hello world!\r\n"
 //! }
 //!
-//! # fn main() -> std::io::Result<()> {
-//! rt::System::new().block_on(
+//! fn main() -> std::io::Result<()> {
+//!     rt::System::new().block_on(
+//!         HttpServer::new(|| {
+//!             App::new().service(web::resource("/").route(web::get().to(index)))
+//!         })
+//!         .bind(("127.0.0.1", 8080))?
+//!         .run()
+//!     )
+//! }
+//! ```
+//!
+//! # Running Actix Web Using `#[tokio::main]`
+//! If you need to run something alongside Actix Web that uses Tokio's work stealing functionality,
+//! you can run Actix Web under `#[tokio::main]`. The [`Server`](crate::dev::Server) object returned
+//! from [`HttpServer::run`](crate::HttpServer::run) can also be [`spawn`]ed, if preferred.
+//!
+//! Note that `actix` actor support (and therefore WebSocket support through `actix-web-actors`)
+//! still require `#[actix_web::main]` since they require a [`System`] to be set up.
+//!
+//! ```no_run
+//! use actix_web::{get, middleware, rt, web, App, HttpRequest, HttpServer};
+//!
+//! #[get("/")]
+//! async fn index(req: HttpRequest) -> &'static str {
+//!     println!("REQ: {:?}", req);
+//!     "Hello world!\r\n"
+//! }
+//!
+//! #[tokio::main]
+//! async fn main() -> std::io::Result<()> {
 //!     HttpServer::new(|| {
-//!         App::new()
-//!             .wrap(middleware::Logger::default())
-//!             .service(web::resource("/").route(web::get().to(index)))
+//!         App::new().service(index)
 //!     })
 //!     .bind(("127.0.0.1", 8080))?
-//!     .workers(1)
 //!     .run()
-//! )
-//! # }
+//!     .await
+//! }
 //! ```
+//!
+//! [^compat]: Crates that use Tokio's [`block_in_place`] will not work with Actix Web. Fortunately,
+//!   the vast majority of Tokio-based crates do not use it.
+//!
+//! [`actix-rt`]: https://docs.rs/actix_rt
+//! [`tokio`]: https://docs.rs/tokio
+//! [Tokio]: https://docs.rs/tokio
+//! [`spawn`]: https://docs.rs/tokio/1/tokio/fn.spawn.html
+//! [`block_in_place`]: https://docs.rs/tokio/1/tokio/task/fn.block_in_place.html
 
 // In particular:
 // - Omit the `Arbiter` types because they have limited value here.