From abea4dde3d30388f8338985e323203d8792dabeb Mon Sep 17 00:00:00 2001
From: Ulf Lilleengen <ulf.lilleengen@gmail.com>
Date: Wed, 20 Dec 2023 10:09:05 +0100
Subject: [PATCH] docs: document most of esp-hosted driver

---
 embassy-net-esp-hosted/src/control.rs | 17 +++++++++++++++++
 embassy-net-esp-hosted/src/lib.rs     |  9 +++++++++
 embassy-net-esp-hosted/src/proto.rs   |  2 ++
 3 files changed, 28 insertions(+)

diff --git a/embassy-net-esp-hosted/src/control.rs b/embassy-net-esp-hosted/src/control.rs
index c86891bc..b141bd6d 100644
--- a/embassy-net-esp-hosted/src/control.rs
+++ b/embassy-net-esp-hosted/src/control.rs
@@ -5,6 +5,7 @@ use heapless::String;
 use crate::ioctl::Shared;
 use crate::proto::{self, CtrlMsg};
 
+/// Errors reported by control.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
@@ -13,30 +14,42 @@ pub enum Error {
     Internal,
 }
 
+/// Handle for managing the network and WiFI state.
 pub struct Control<'a> {
     state_ch: ch::StateRunner<'a>,
     shared: &'a Shared,
 }
 
+/// WiFi mode.
 #[allow(unused)]
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 enum WifiMode {
+    /// No mode.
     None = 0,
+    /// Client station.
     Sta = 1,
+    /// Access point mode.
     Ap = 2,
+    /// Repeater mode.
     ApSta = 3,
 }
 
 pub use proto::CtrlWifiSecProt as Security;
 
+/// WiFi status.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Status {
+    /// Service Set Identifier.
     pub ssid: String<32>,
+    /// Basic Service Set Identifier.
     pub bssid: [u8; 6],
+    /// Received Signal Strength Indicator.
     pub rssi: i32,
+    /// WiFi channel.
     pub channel: u32,
+    /// Security mode.
     pub security: Security,
 }
 
@@ -65,6 +78,7 @@ impl<'a> Control<'a> {
         Self { state_ch, shared }
     }
 
+    /// Initialize device.
     pub async fn init(&mut self) -> Result<(), Error> {
         debug!("wait for init event...");
         self.shared.init_wait().await;
@@ -82,6 +96,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Get the current status.
     pub async fn get_status(&mut self) -> Result<Status, Error> {
         let req = proto::CtrlMsgReqGetApConfig {};
         ioctl!(self, ReqGetApConfig, RespGetApConfig, req, resp);
@@ -95,6 +110,7 @@ impl<'a> Control<'a> {
         })
     }
 
+    /// Connect to the network identified by ssid using the provided password.
     pub async fn connect(&mut self, ssid: &str, password: &str) -> Result<(), Error> {
         let req = proto::CtrlMsgReqConnectAp {
             ssid: unwrap!(String::try_from(ssid)),
@@ -108,6 +124,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Disconnect from any currently connected network.
     pub async fn disconnect(&mut self) -> Result<(), Error> {
         let req = proto::CtrlMsgReqGetStatus {};
         ioctl!(self, ReqDisconnectAp, RespDisconnectAp, req, resp);
diff --git a/embassy-net-esp-hosted/src/lib.rs b/embassy-net-esp-hosted/src/lib.rs
index d61eaef3..ce7f39dc 100644
--- a/embassy-net-esp-hosted/src/lib.rs
+++ b/embassy-net-esp-hosted/src/lib.rs
@@ -97,12 +97,14 @@ enum InterfaceType {
 const MAX_SPI_BUFFER_SIZE: usize = 1600;
 const HEARTBEAT_MAX_GAP: Duration = Duration::from_secs(20);
 
+/// Shared driver state.
 pub struct State {
     shared: Shared,
     ch: ch::State<MTU, 4, 4>,
 }
 
 impl State {
+    /// Shared state for the
     pub fn new() -> Self {
         Self {
             shared: Shared::new(),
@@ -111,8 +113,13 @@ impl State {
     }
 }
 
+/// Type alias for network driver.
 pub type NetDriver<'a> = ch::Device<'a, MTU>;
 
+/// Create a new esp-hosted driver using the provided state, SPI peripheral and pins.
+///
+/// Returns a device handle for interfacing with embassy-net, a control handle for
+/// interacting with the driver, and a runner for communicating with the WiFi device.
 pub async fn new<'a, SPI, IN, OUT>(
     state: &'a mut State,
     spi: SPI,
@@ -144,6 +151,7 @@ where
     (device, Control::new(state_ch, &state.shared), runner)
 }
 
+/// Runner for communicating with the WiFi device.
 pub struct Runner<'a, SPI, IN, OUT> {
     ch: ch::Runner<'a, MTU>,
     state_ch: ch::StateRunner<'a>,
@@ -166,6 +174,7 @@ where
 {
     async fn init(&mut self) {}
 
+    /// Run the packet processing.
     pub async fn run(mut self) -> ! {
         debug!("resetting...");
         self.reset.set_low().unwrap();
diff --git a/embassy-net-esp-hosted/src/proto.rs b/embassy-net-esp-hosted/src/proto.rs
index 8ceb1579..b42ff62f 100644
--- a/embassy-net-esp-hosted/src/proto.rs
+++ b/embassy-net-esp-hosted/src/proto.rs
@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use heapless::{String, Vec};
 
 /// internal supporting structures for CtrlMsg