From 0304a10b2feb16010b08f43a14c606522e95a3e7 Mon Sep 17 00:00:00 2001
From: Jesse Braham <jesse@beta7.io>
Date: Fri, 27 Oct 2023 08:00:39 -0700
Subject: [PATCH] Documentation improvements for `esp-hal-procmacros`

---
 esp-hal-procmacros/Cargo.toml |  4 +--
 esp-hal-procmacros/README.md  |  8 ++++-
 esp-hal-procmacros/src/lib.rs | 66 ++++++++++++++++++++++++-----------
 3 files changed, 55 insertions(+), 23 deletions(-)

diff --git a/esp-hal-procmacros/Cargo.toml b/esp-hal-procmacros/Cargo.toml
index 8f7fab7a1..859d73505 100644
--- a/esp-hal-procmacros/Cargo.toml
+++ b/esp-hal-procmacros/Cargo.toml
@@ -8,14 +8,14 @@ repository   = "https://github.com/esp-rs/esp-hal"
 license      = "MIT OR Apache-2.0"
 
 [package.metadata.docs.rs]
-features = ["esp32c3", "interrupt", "ram"]
+features = ["esp32c3", "embassy", "interrupt", "ram"]
 
 [lib]
 proc-macro = true
 
 [dependencies]
 darling          = "0.20.3"
-litrs            = "0.4.0"
+litrs            = "0.4.1"
 object           = { version = "0.32.1", optional = true }
 proc-macro-crate = "2.0.0"
 proc-macro-error = "1.0.4"
diff --git a/esp-hal-procmacros/README.md b/esp-hal-procmacros/README.md
index d6d90093a..828772547 100644
--- a/esp-hal-procmacros/README.md
+++ b/esp-hal-procmacros/README.md
@@ -5,7 +5,13 @@
 ![Crates.io](https://img.shields.io/crates/l/esp-hal-procmacros?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)
 
-Procedural macros for placing statics and functions into RAM, and for marking interrupt handlers.
+Procedural macros for use with the `esp-hal` family of HAL packages.
+
+Provides macros for:
+
+- Placing statics and functions into RAM
+- Marking interrupt handlers
+- Automatically creating an `embassy` executor instance and spawning the defined entry point
 
 ## [Documentation]
 
diff --git a/esp-hal-procmacros/src/lib.rs b/esp-hal-procmacros/src/lib.rs
index 3b6cf14bb..23974262d 100644
--- a/esp-hal-procmacros/src/lib.rs
+++ b/esp-hal-procmacros/src/lib.rs
@@ -1,31 +1,65 @@
-//! Procedural macros
-//!
 //! ## Overview
-//! The `esp-hal-procmacros` module provides procedural macros for placing
-//! statics and functions into RAM and for marking interrupt handlers on ESP
-//! microcontrollers.
+//!
+//! Procedural macros for use with the `esp-hal` family of HAL packages. In
+//! general, you should not need to depend on this package directly, as the
+//! relevant procmacros are re-exported by the various HAL packages.
+//!
+//! Provides macros for:
+//!
+//! - Placing statics and functions into RAM
+//! - Marking interrupt handlers
+//! - Automatically creating an `embassy` executor instance and spawning the
+//!   defined entry point
 //!
 //! These macros offer developers a convenient way to control memory placement
 //! and define interrupt handlers in their embedded applications, allowing for
 //! optimized memory usage and precise handling of hardware interrupts.
 //!
 //! Key Components:
-//!   - [ram](attr.ram.html) - Attribute macro for placing statics and functions
-//!     into specific memory sections, such as SRAM or RTC RAM (slow or fast)
-//!     with different initialization options. Supported options are:
-//!       - `rtc_fast` - Use RTC fast RAM
-//!       - `rtc_slow` - Use RTC slow RAM (not all targets support slow RTC RAM)
-//!       - `uninitialized` - Skip initialization of the memory
-//!       - `zeroed` - Initialize the memory to zero
 //!  - [interrupt](attr.interrupt.html) - Attribute macro for marking interrupt
 //!    handlers. Interrupt handlers are used to handle specific hardware
 //!    interrupts generated by peripherals.<br> The macro allows users to
 //!    specify the interrupt name explicitly or use the function name to match
 //!    the interrupt.
+//!  - [main](attr.main.html) - Creates a new `executor`` instance and declares
+//!    an application entry point spawning the corresponding function body as an
+//!    async task.
+//!  - [ram](attr.ram.html) - Attribute macro for placing statics and functions
+//!    into specific memory sections, such as SRAM or RTC RAM (slow or fast)
+//!    with different initialization options. Supported options are:
+//!      - `rtc_fast` - Use RTC fast RAM
+//!      - `rtc_slow` - Use RTC slow RAM (not all targets support slow RTC RAM)
+//!      - `uninitialized` - Skip initialization of the memory
+//!      - `zeroed` - Initialize the memory to zero
 //!  
 //! ## Examples
 //!
+//! #### `interrupt` macro
+//!
+//! Requires the `interrupt` feature to be enabled.
+//!
+//! ```no_run
+//! #[interrupt]
+//! fn INTR_NAME() {
+//!     // Interrupt handling code here
+//! }
+//! ```
+//!
+//! #### `main` macro
+//!
+//! Requires the `embassy` feature to be enabled.
+//!
+//! ```no_run
+//! #[main]
+//! async fn main(spawner: Spawner) -> ! {
+//!     // Your application's entry point
+//! }
+//! ```
+//!
 //! #### `ram` macro
+//!
+//! Requires the `ram` feature to be enabled.
+//!
 //! ```no_run
 //! #[ram(rtc_fast)]
 //! static mut SOME_INITED_DATA: [u8; 2] = [0xaa, 0xbb];
@@ -36,14 +70,6 @@
 //! #[ram(rtc_fast, zeroed)]
 //! static mut SOME_ZEROED_DATA: [u8; 8] = [0; 8];
 //! ```
-//!
-//! #### `interrupt` macro
-//! ```no_run
-//! #[interrupt]
-//! fn INTR_NAME() {
-//!     // Interrupt handling code here
-//! }
-//! ```
 
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]