docs: document feature flags (#2081)

1 files changed, 70 insertions, 5 deletions

diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index b8f1421c..7355ab70 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -49,10 +49,6 @@
 //! section, we will take a brief tour of Tokio, summarizing the major APIs and
 //! their uses.
 //!
-//! Note that Tokio uses [Cargo feature flags][features] to allow users to
-//! control what features are present, so that unused code can be eliminated.
-//! This documentation also lists what feature flags are necessary to enable each API.
-//!
 //! The easiest way to get started is to enable all features. Do this by
 //! enabling the `full` feature flag:
 //!
@@ -60,7 +56,76 @@
 //! tokio = { version = "0.2", features = ["full"] }
 //! ```
 //!
-//! [features]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
+//! ## Feature flags
+//!
+//! Tokio uses a set of [feature flags] to reduce the amount of compiled code. It
+//! is possible to just enable certain features over others. By default, Tokio
+//! does not enable any features but allows one to enable a subset for their use
+//! case. Below is a list of the available feature flags. You may also notice
+//! above each function, struct and trait there is a set of feature flags
+//! that are required for that item to be enabled. If you are new to Tokio it is
+//! recommended that you use the `full` feature flag which will enable everything.
+//! Beware though that this will pull in many extra dependencies that you may not
+//! need.
+//!
+//! - `full`: Enables all Tokio features and every API will be available.
+//! - `rt-core`: Enables `tokio::spawn` and the basic (single-threaded) scheduler.
+//! - `rt-threaded`: Enables the heavier, multi-threaded, work-stealing scheduler.
+//! - `rt-util`: Enables non-scheduler utilities.
+//! - `io-driver`: Enables the `mio` based IO driver.
+//! - `io-util`: Enables the IO based `Ext` traits.
+//! - `io-std`: Enable `Stdout`, `Stdin` and `Stderr` types.
+//! - `net`: Enables `tokio::net` types such as `TcpStream`, `UnixStream` and `UdpSocket`.
+//! - `tcp`: Enables all `tokio::net::tcp` types.
+//! - `udp`: Enables all `tokio::net::udp` types.
+//! - `uds`: Enables all `tokio::net::unix` types.
+//! - `time`: Enables `tokio::time` types and allows the schedulers to enable
+//! the built in timer.
+//! - `process`: Enables `tokio::process` types.
+//! - `macros`: Enables `#[tokio::main]` and `#[tokio::test]` macros.
+//! - `sync`: Enables all `tokio::sync` types.
+//! - `stream`: Enables optional `Stream` implementations for types within Tokio.
+//! - `signal`: Enables all `tokio::signal` types.
+//! - `fs`: Enables `tokio::fs` types.
+//! - `dns`: Enables async `tokio::net::ToSocketAddrs`.
+//! - `test-util`: Enables testing based infrastructure for the Tokio runtime.
+//! - `blocking`: Enables `block_in_place` and `spawn_blocking`.
+//!
+//! _Note: `AsyncRead` and `AsyncWrite` do not require any features and are
+//! enabled by default._
+//!
+//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
+//!
+//! ### Authoring applications
+//!
+//! Tokio is great for writing applications and most users in this case shouldn't
+//! worry to much about what features they should pick. If you're unsure, we suggest
+//! going with `full` to ensure that you don't run into any road blocks while you're
+//! building your application.
+//!
+//! #### Example
+//!
+//! This example shows the quickest way to get started with Tokio.
+//!
+//! ```toml
+//! tokio = { version = "0.2", features = ["full"] }
+//! ```
+//!
+//! ### Authoring libraries
+//!
+//! As a library author your goal should be to provide the lighest weight crate
+//! that is based on Tokio. To achieve this you should ensure that you only enable
+//! the features you need. This allows users to pick up your crate without having
+//! to enable unnecessary features.
+//!
+//! #### Example
+//!
+//! This example shows how you may want to import features for a library that just
+//! needs to `tokio::spawn` and use a `TcpStream`.
+//!
+//! ```toml
+//! tokio = { version = "0.2", features = ["rt-core", "tcp"] }
+//! ```
 //!
 //! ## Working With Tasks
 //!