Revise API docs (esp-rs#330)

* Revise API docs

* Rephrase description of `WifiStack`

* Formatting

esp-wifi/src/ble/controller/mod.rs

@@ -5,6 +5,7 @@ use crate::EspWifiInitialization;
 
 use super::{read_hci, read_next, send_hci};
 
+/// A blocking HCI connector
 pub struct BleConnector<'d> {
     _device: PeripheralRef<'d, crate::hal::peripherals::BT>,
 }
@@ -76,6 +77,7 @@ impl Write for BleConnector<'_> {
     }
 }
 
+/// Async Interface
 #[cfg(feature = "async")]
 pub mod asynch {
     use core::task::Poll;
@@ -95,6 +97,7 @@ pub mod asynch {
         HCI_WAKER.wake();
     }
 
+    /// Async HCI connector
     pub struct BleConnector<'d> {
         _device: PeripheralRef<'d, crate::hal::peripherals::BT>,
     }

esp-wifi/src/ble/mod.rs

@@ -1,3 +1,5 @@
+//! Bluetooth Low Energy HCI interface
+
 #[cfg(any(esp32, esp32c3, esp32s3))]
 pub(crate) mod btdm;
 
@@ -19,15 +21,15 @@ pub(crate) use ble::send_hci;
 
 pub mod controller;
 
-pub unsafe extern "C" fn malloc(size: u32) -> *mut crate::binary::c_types::c_void {
+pub(crate) unsafe extern "C" fn malloc(size: u32) -> *mut crate::binary::c_types::c_void {
     crate::compat::malloc::malloc(size as usize).cast()
 }
 
-pub unsafe extern "C" fn malloc_internal(size: u32) -> *mut crate::binary::c_types::c_void {
+pub(crate) unsafe extern "C" fn malloc_internal(size: u32) -> *mut crate::binary::c_types::c_void {
     crate::compat::malloc::malloc(size as usize).cast()
 }
 
-pub unsafe extern "C" fn free(ptr: *mut crate::binary::c_types::c_void) {
+pub(crate) unsafe extern "C" fn free(ptr: *mut crate::binary::c_types::c_void) {
     crate::compat::malloc::free(ptr.cast())
 }
 

esp-wifi/src/lib.rs

@@ -164,10 +164,10 @@ fn init_heap() {
 }
 
 #[cfg(any(esp32c3, esp32c2, esp32c6))]
-pub type EspWifiTimer = Alarm<Target, 0>;
+pub(crate) type EspWifiTimer = Alarm<Target, 0>;
 
 #[cfg(any(esp32, esp32s3, esp32s2))]
-pub type EspWifiTimer = hal::timer::Timer<hal::timer::Timer0<hal::peripherals::TIMG1>>;
+pub(crate) type EspWifiTimer = hal::timer::Timer<hal::timer::Timer0<hal::peripherals::TIMG1>>;
 
 #[derive(Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]

esp-wifi/src/wifi/mod.rs

@@ -1,3 +1,5 @@
+//! WiFi
+
 pub(crate) mod os_adapter;
 pub(crate) mod state;
 
@@ -103,6 +105,7 @@ impl AuthMethodExt for AuthMethod {
     }
 }
 
+/// Wifi Mode (Sta or Ap)
 #[derive(Debug, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum WifiMode {
@@ -118,13 +121,15 @@ impl WifiMode {
         WifiMode::try_from(mode)
     }
 
+    /// Returns true if this mode is STA
     pub fn is_sta(&self) -> bool {
         match self {
             WifiMode::Sta => true,
             WifiMode::Ap => false,
         }
     }
 
+    /// Returns true if this mode is AP
     pub fn is_ap(&self) -> bool {
         match self {
             WifiMode::Sta => false,
@@ -192,6 +197,7 @@ const TX_QUEUE_SIZE: usize = crate::CONFIG.tx_queue_size;
 pub(crate) static DATA_QUEUE_RX: Mutex<RefCell<SimpleQueue<EspWifiPacketBuffer, RX_QUEUE_SIZE>>> =
     Mutex::new(RefCell::new(SimpleQueue::new()));
 
+/// Common errors
 #[derive(Debug, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum WifiError {
@@ -201,6 +207,8 @@ pub enum WifiError {
     Disconnected,
     UnknownWifiMode,
 }
+
+/// Events generated by the WiFi driver
 #[repr(i32)]
 #[derive(Debug, FromPrimitive, EnumSetType)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -229,6 +237,7 @@ pub enum WifiEvent {
     StaBeaconTimeout,
 }
 
+/// Error originating from the underlying drivers
 #[repr(i32)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, FromPrimitive)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -371,7 +380,7 @@ pub(crate) fn coex_initialize() -> i32 {
     }
 }
 
-pub unsafe extern "C" fn coex_init() -> i32 {
+pub(crate) unsafe extern "C" fn coex_init() -> i32 {
     #[cfg(coex)]
     {
         debug!("coex-init");
@@ -591,19 +600,21 @@ static mut G_CONFIG: wifi_init_config_t = wifi_init_config_t {
     magic: WIFI_INIT_CONFIG_MAGIC as i32,
 };
 
+/// Get the STA MAC address
 pub fn get_sta_mac(mac: &mut [u8; 6]) {
     unsafe {
         read_mac(mac as *mut u8, 0);
     }
 }
 
+/// Get the AP MAC address
 pub fn get_ap_mac(mac: &mut [u8; 6]) {
     unsafe {
         read_mac(mac as *mut u8, 1);
     }
 }
 
-pub fn wifi_init() -> Result<(), WifiError> {
+pub(crate) fn wifi_init() -> Result<(), WifiError> {
     unsafe {
         G_CONFIG.wpa_crypto_funcs = g_wifi_default_wpa_crypto_funcs;
         G_CONFIG.feature_caps = g_wifi_feature_caps;
@@ -695,7 +706,7 @@ unsafe extern "C" fn esp_wifi_tx_done_cb(
     embassy::TRANSMIT_WAKER.wake();
 }
 
-pub fn wifi_start() -> Result<(), WifiError> {
+pub(crate) fn wifi_start() -> Result<(), WifiError> {
     unsafe {
         esp_wifi_result!(esp_wifi_start())?;
 
@@ -833,7 +844,7 @@ pub struct ScanConfig<'a> {
     pub scan_type: ScanTypeConfig,
 }
 
-pub fn wifi_start_scan(
+pub(crate) fn wifi_start_scan(
     block: bool,
     ScanConfig {
         ssid,
@@ -891,6 +902,7 @@ pub fn wifi_start_scan(
     unsafe { esp_wifi_scan_start(&scan_config, block) }
 }
 
+/// Create a new [WifiDevice] and [WifiController] from the given config
 pub fn new_with_config<'d>(
     inited: &EspWifiInitialization,
     device: impl Peripheral<P = crate::hal::peripherals::WIFI> + 'd,
@@ -908,6 +920,7 @@ pub fn new_with_config<'d>(
     ))
 }
 
+/// Create a new [WifiDevice] and [WifiController] for the given mode
 pub fn new_with_mode<'d>(
     inited: &EspWifiInitialization,
     device: impl Peripheral<P = crate::hal::peripherals::WIFI> + 'd,
@@ -1119,6 +1132,7 @@ impl Device for WifiDevice<'_> {
     }
 }
 
+#[doc(hidden)]
 #[derive(Debug, Default)]
 pub struct WifiRxToken {}
 
@@ -1131,6 +1145,7 @@ impl RxToken for WifiRxToken {
     }
 }
 
+#[doc(hidden)]
 #[derive(Debug, Default)]
 pub struct WifiTxToken {}
 
@@ -1199,7 +1214,7 @@ fn esp_wifi_can_send() -> bool {
 // FIXME data here has to be &mut because of `esp_wifi_internal_tx` signature, requiring a *mut ptr to the buffer
 // Casting const to mut is instant UB, even though in reality `esp_wifi_internal_tx` copies the buffer into its own memory and
 // does not modify
-pub fn esp_wifi_send_data(interface: wifi_interface_t, data: &mut [u8]) {
+pub(crate) fn esp_wifi_send_data(interface: wifi_interface_t, data: &mut [u8]) {
     trace!("sending... {} bytes", data.len());
     dump_packet_info(data);
 
@@ -1380,6 +1395,7 @@ fn dump_packet_info(_buffer: &[u8]) {
     }
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! esp_wifi_result {
     ($value:expr) => {{

esp-wifi/src/wifi/state.rs

@@ -3,6 +3,7 @@ use super::WifiEvent;
 use atomic_enum::atomic_enum;
 use core::sync::atomic::Ordering;
 
+/// Wifi interface state
 #[atomic_enum]
 #[derive(PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -35,10 +36,12 @@ impl From<WifiEvent> for WifiState {
 pub(crate) static STA_STATE: AtomicWifiState = AtomicWifiState::new(WifiState::Invalid);
 pub(crate) static AP_STATE: AtomicWifiState = AtomicWifiState::new(WifiState::Invalid);
 
+/// Get the current state of the AP
 pub fn get_ap_state() -> WifiState {
     AP_STATE.load(Ordering::Relaxed)
 }
 
+/// Get the current state of the STA
 pub fn get_sta_state() -> WifiState {
     STA_STATE.load(Ordering::Relaxed)
 }

esp-wifi/src/wifi/utils.rs

@@ -1,3 +1,5 @@
+//! Convenience utilities for non-async code
+
 use smoltcp::{
     iface::{Config, Interface, SocketSet, SocketStorage},
     socket::dhcpv4::Socket as Dhcpv4Socket,