From 67637b348a88ce3e035affe507bac17992851246 Mon Sep 17 00:00:00 2001
From: Sabnock <24715302+Sabnock01@users.noreply.github.com>
Date: Tue, 9 Jun 2026 07:22:46 -0500
Subject: [PATCH] macros: clarify `tokio::main` expansion (#8193)

---
 tokio-macros/src/lib.rs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/tokio-macros/src/lib.rs b/tokio-macros/src/lib.rs
index 3b4f46c76..e3791b72f 100644
--- a/tokio-macros/src/lib.rs
+++ b/tokio-macros/src/lib.rs
@@ -29,10 +29,11 @@ use proc_macro::TokenStream;
 /// powerful interface.
 ///
 /// Note: This macro can be used on any function and not just the `main`
-/// function. Using it on a non-main function makes the function behave as if it
-/// was synchronous by starting a new runtime each time it is called. If the
-/// function is called often, it is preferable to create the runtime using the
-/// runtime builder so the runtime can be reused across calls.
+/// function. Although the function is written with `async fn`, this macro
+/// expands it to a synchronous function that starts a runtime each time it is
+/// called. If the function is called often, it is preferable to create the
+/// runtime using the runtime builder so the runtime can be reused across calls.
+/// For details on the expansion, see [Bridging with sync code][bridging].
 ///
 /// # Non-worker async function
 ///
@@ -308,6 +309,7 @@ use proc_macro::TokenStream;
 /// [`Builder::unhandled_panic`]: ../tokio/runtime/struct.Builder.html#method.unhandled_panic
 /// [unstable]: ../tokio/index.html#unstable-features
 /// [local runtime]: ../tokio/runtime/struct.LocalRuntime.html
+/// [bridging]: https://tokio.rs/tokio/topics/bridging#what-tokiomain-expands-to
 #[proc_macro_attribute]
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::main(args.into(), item.into(), true).into()