From 38cab933301b60a7fa730bb999bc08cdb5529476 Mon Sep 17 00:00:00 2001
From: Igor Aleksanov <popzxc@yandex.ru>
Date: Sat, 5 Sep 2020 21:22:47 +0300
Subject: runtime: improve runtime vs #[tokio::main] doc (#2820)

---
 tokio-macros/src/lib.rs  | 14 ++++++++++++--
 tokio/src/lib.rs         |  7 ++++---
 tokio/src/runtime/mod.rs |  6 +++---
 3 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/tokio-macros/src/lib.rs b/tokio-macros/src/lib.rs
index 79d06a70..09733ba5 100644
--- a/tokio-macros/src/lib.rs
+++ b/tokio-macros/src/lib.rs
@@ -26,7 +26,12 @@ use proc_macro::TokenStream;
 
 /// Marks async function to be executed by selected runtime. This macro helps set up a `Runtime`
 /// without requiring the user to use [Runtime](../tokio/runtime/struct.Runtime.html) or
-/// [Builder](../tokio/runtime/struct.builder.html) directly.
+/// [Builder](../tokio/runtime/struct.Builder.html) directly.
+///
+/// Note: This macro is designed to be simplistic and targets applications that do not require
+/// a complex setup. If provided functionality is not sufficient, user may be interested in
+/// using [Builder](../tokio/runtime/struct.Builder.html), which provides a more powerful
+/// interface.
 ///
 /// ## Options:
 ///
@@ -133,7 +138,12 @@ pub fn main_threaded(args: TokenStream, item: TokenStream) -> TokenStream {
 
 /// Marks async function to be executed by selected runtime. This macro helps set up a `Runtime`
 /// without requiring the user to use [Runtime](../tokio/runtime/struct.Runtime.html) or
-/// [Builder](../tokio/runtime/struct.builder.html) directly.
+/// [Builder](../tokio/runtime/struct.Builder.html) directly.
+///
+/// Note: This macro is designed to be simplistic and targets applications that do not require
+/// a complex setup. If provided functionality is not sufficient, user may be interested in
+/// using [Builder](../tokio/runtime/struct.Builder.html), which provides a more powerful
+/// interface.
 ///
 /// ## Options:
 ///
diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index 7bf9f743..b31b478d 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -196,9 +196,10 @@
 //!
 //! Finally, Tokio provides a _runtime_ for executing asynchronous tasks. Most
 //! applications can use the [`#[tokio::main]`][main] macro to run their code on the
-//! Tokio runtime. In use-cases where manual control over the runtime is
-//! required, the [`tokio::runtime`] module provides APIs for configuring and
-//! managing runtimes.
+//! Tokio runtime. However, this macro provides only basic configuration options. As
+//! an alternative, the [`tokio::runtime`] module provides more powerful APIs for configuring
+//! and managing runtimes. You should use that module if the `#[tokio::main]` macro doesn't
+//! provide the functionality you need.
 //!
 //! Using the runtime requires the "rt-core" or "rt-threaded" feature flags, to
 //! enable the basic [single-threaded scheduler][rt-core] and the [thread-pool
diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs
index 9d26446b..bec0ecd5 100644
--- a/tokio/src/runtime/mod.rs
+++ b/tokio/src/runtime/mod.rs
@@ -10,14 +10,14 @@
 //! * A **timer** for scheduling work to run after a set period of time.
 //!
 //! Tokio's [`Runtime`] bundles all of these services as a single type, allowing
-//! them to be started, shut down, and configured together. However, most
-//! applications won't need to use [`Runtime`] directly. Instead, they can
+//! them to be started, shut down, and configured together. However, often
+//! it is not required to configure a [`Runtime`] manually, and user may just
 //! use the [`tokio::main`] attribute macro, which creates a [`Runtime`] under
 //! the hood.
 //!
 //! # Usage
 //!
-//! Most applications will use the [`tokio::main`] attribute macro.
+//! When no fine tuning is required, the [`tokio::main`] attribute macro can be used.
 //!
 //! ```no_run
 //! use tokio::net::TcpListener;
-- 
cgit v1.2.3