macros: document basic_scheduler option (#2697)

1 files changed, 29 insertions, 0 deletions

diff --git a/tokio-macros/src/lib.rs b/tokio-macros/src/lib.rs
index 64cdc4f1..1fd445d8 100644
--- a/tokio-macros/src/lib.rs
+++ b/tokio-macros/src/lib.rs
@@ -30,9 +30,12 @@ use proc_macro::TokenStream;
 ///
 /// ## Options:
 ///
+/// If you want to set the number of worker threads used for asynchronous code, use the
+/// `core_threads` option.
 ///
 /// - `core_threads=n` - Sets core threads to `n` (requires `rt-threaded` feature).
 /// - `max_threads=n` - Sets max threads to `n` (requires `rt-core` or `rt-threaded` feature).
+/// - `basic_scheduler` - Use the basic schduler (requires `rt-core`).
 ///
 /// ## Function arguments:
 ///
@@ -64,6 +67,32 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
+/// ### Using basic scheduler
+///
+/// The basic scheduler is single-threaded.
+///
+/// ```rust
+/// #[tokio::main(basic_scheduler)]
+/// async fn main() {
+///     println!("Hello world");
+/// }
+/// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new()
+///         .basic_scheduler()
+///         .enable_all()
+///         .build()
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
 /// ### Set number of core threads
 ///
 /// ```rust