From f500f1eef08db4e052967ecbbbf4e316e316ccaf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1niel=20Buga?= <bugadani@gmail.com>
Date: Tue, 14 Oct 2025 16:54:27 +0200
Subject: [PATCH] Clarify some things (#4349)

---
 esp-rtos/README.md          |  2 +-
 esp-rtos/src/embassy/mod.rs |  3 ++-
 esp-rtos/src/lib.rs         | 10 ++++++----
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/esp-rtos/README.md b/esp-rtos/README.md
index 8393872f4..9b75f0ac1 100644
--- a/esp-rtos/README.md
+++ b/esp-rtos/README.md
@@ -6,7 +6,7 @@
 ![Crates.io](https://img.shields.io/crates/l/esp-rtos?labelColor=1C2C2E&style=flat-square)
 [![Matrix](https://img.shields.io/matrix/esp-rs:matrix.org?label=join%20matrix&labelColor=1C2C2E&color=BEC5C9&logo=matrix&style=flat-square)](https://matrix.to/#/#esp-rs:matrix.org)
 
-This crate implements [`esp-radio-rtos-driver`](https://crates.io/crates/esp-radio-rtos-driver) for firmwares using [esp-hal](https://crates.io/crates/esp-hal) without any additional software platform.
+An RTOS (Real-Time Operating System) implementation for esp-hal. This crate provides the runtime necessary to run `async` code on top of esp-hal, and implements the necessary capabilities (threads, queues, etc.) required by esp-radio.
 
 ## Minimum Supported Rust Version (MSRV)
 
diff --git a/esp-rtos/src/embassy/mod.rs b/esp-rtos/src/embassy/mod.rs
index d0205a819..90105b267 100644
--- a/esp-rtos/src/embassy/mod.rs
+++ b/esp-rtos/src/embassy/mod.rs
@@ -43,7 +43,8 @@ pub trait Callbacks {
 /// Thread-mode executor.
 ///
 /// This executor runs in an OS thread, meaning the scheduler needs to be started before using any
-/// async operations.
+/// async operations. If you wish to write async code without the scheduler running, consider
+/// using the [`InterruptExecutor`].
 #[cfg_attr(
     multi_core,
     doc = r"
diff --git a/esp-rtos/src/lib.rs b/esp-rtos/src/lib.rs
index 630e7a42b..9254bc434 100644
--- a/esp-rtos/src/lib.rs
+++ b/esp-rtos/src/lib.rs
@@ -2,8 +2,10 @@
     all(docsrs, not(not_really_docsrs)),
     doc = "<div style='padding:30px;background:#810;color:#fff;text-align:center;'><p>You might want to <a href='https://docs.espressif.com/projects/rust/'>browse the <code>esp-hal</code> documentation on the esp-rs website</a> instead.</p><p>The documentation here on <a href='https://docs.rs'>docs.rs</a> is built for a single chip only (ESP32-C6, in particular), while on the esp-rs website you can select your exact chip from the list of supported devices. Available peripherals and their APIs change depending on the chip.</p></div>\n\n<br/>\n\n"
 )]
-//! This crate provides RTOS functionality for `esp-radio`, and provides executors to enable
-//! running `async` code.
+//! An RTOS (Real-Time Operating System) implementation for esp-hal.
+//!
+//! This crate provides the runtime necessary to run `async` code on top of esp-hal,
+//! and implements the necessary capabilities (threads, queues, etc.) required by esp-radio.
 //!
 //! ## Setup
 //!
@@ -60,8 +62,8 @@ esp_rtos::start_second_core(
 //! ```
 //! 
 //! To write `async` code, enable the `embassy` feature, and mark the main function with `#[esp_rtos::main]`.
-//! Note that, to create async tasks, you will need the `task` macro from the `embassy-executor` crate. Do
-//! NOT enable any of the `arch-*` features on `embassy-executor`.
+//! This will create a thread-mode executor on the main thread. Note that, to create async tasks, you will need
+//! the `task` macro from the `embassy-executor` crate. Do NOT enable any of the `arch-*` features on `embassy-executor`.
 //!
 //! ## Additional configuration
 #![doc = ""]