runtime: improve runtime vs #[tokio::main] doc (#2820)

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:
 ///

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

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;