docs: module-level documentation, channel capacity rationale, architecture in main.rs

src/channel.rs

@@ -1,3 +1,11 @@
+//! Inter-task communication channels.
+//!
+//! Each channel connects exactly two tasks:
+//! - [`CommandChannel`]: USB → Radio (host commands)
+//! - [`ResponseChannel`]: Radio → USB (firmware responses)
+//! - [`DisplayCommandChannel`]: USB → Display (on/off/reset)
+//! - [`StatusWatch`]: Radio → Display (observable radio state)
+
 use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
 use embassy_sync::channel::Channel;
 use embassy_sync::watch::Watch;
@@ -13,16 +21,16 @@ pub enum DisplayCommand {
     Reset,
 }
 
-/// USB-to-display command channel.
+/// USB-to-display command channel (depth 4: display commands are rare events).
 pub type DisplayCommandChannel = Channel<CriticalSectionRawMutex, DisplayCommand, 4>;
 
-/// Host-to-radio command channel.
+/// Host-to-radio command channel (depth 16: buffer bursty host command sequences).
 pub type CommandChannel = Channel<CriticalSectionRawMutex, Command, 16>;
 
-/// Radio-to-host response channel.
+/// Radio-to-host response channel (depth 32: buffer RX packets while USB writes).
 pub type ResponseChannel = Channel<CriticalSectionRawMutex, Response, 32>;
 
-/// Observable radio status for the display task.
+/// Observable radio status for the display task (2 slots: latest + previous).
 pub type StatusWatch = Watch<CriticalSectionRawMutex, RadioStatus, 2>;
 
 /// Current radio state exposed to observers (e.g. display).

src/display/mod.rs

@@ -1,3 +1,5 @@
+//! OLED display driver with radio status dashboard.
+
 mod render;
 mod task;
 pub use task::display_task;

src/main.rs

@@ -1,3 +1,17 @@
+//! DongLoRa firmware — transparent LoRa radio over USB.
+//!
+//! Three async tasks communicate via static channels:
+//!
+//! ```text
+//! usb_task ──Command──► radio_task ──► SX1262
+//!          ◄──Response──     │
+//!                       StatusWatch
+//!                            ▼
+//!                      display_task (optional)
+//! ```
+//!
+//! The host drives everything. The radio idles until commanded.
+
 #![no_std]
 #![no_main]
 

src/radio/mod.rs

@@ -1,2 +1,4 @@
+//! LoRa radio control via SX1262.
+
 mod task;
 pub use task::radio_task;

src/usb/mod.rs

@@ -1,2 +1,4 @@
+//! USB CDC-ACM interface with COBS-framed command/response protocol.
+
 mod task;
 pub use task::usb_task;