Docs & README changes for release (esp-rs#263)

* Make internal functions/structs private where possible

* Top level docs

* Rework README, move examples into own file
* Include README as top level docs in esp-wifi

* Document public items

esp-wifi/src/common_adapter/mod.rs

@@ -31,13 +31,13 @@ pub(crate) static mut RANDOM_GENERATOR: Option<Rng> = None;
 
 pub(crate) static mut RADIO_CLOCKS: Option<RadioClockControl> = None;
 
-pub fn init_rng(rng: Rng) {
+pub(crate) fn init_rng(rng: Rng) {
     unsafe {
         crate::common_adapter::RANDOM_GENERATOR = Some(core::mem::transmute(rng));
     }
 }
 
-pub fn init_radio_clock_control(rcc: RadioClockControl) {
+pub(crate) fn init_radio_clock_control(rcc: RadioClockControl) {
     unsafe {
         crate::common_adapter::RADIO_CLOCKS = Some(core::mem::transmute(rcc));
     }

esp-wifi/src/lib.rs

@@ -4,6 +4,7 @@
 #![feature(linkage)]
 #![cfg_attr(feature = "async", feature(async_fn_in_trait))]
 #![cfg_attr(feature = "async", allow(incomplete_features))]
+#![doc = include_str!("../../README.md")]
 
 // MUST be the first module
 mod fmt;
@@ -82,12 +83,13 @@ pub mod tasks;
 
 pub(crate) mod memory_fence;
 
-pub use critical_section;
+use critical_section;
 use timer::{get_systimer_count, TICKS_PER_SECOND};
 
 #[cfg(all(feature = "embedded-svc", feature = "wifi"))]
 pub mod wifi_interface;
 
+/// Return the current systimer time in milliseconds
 pub fn current_millis() -> u64 {
     get_systimer_count() / (TICKS_PER_SECOND / 1000)
 }
@@ -117,6 +119,7 @@ const DEFAULT_TICK_RATE_HZ: u32 = 100;
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[toml_cfg::toml_config]
+/// Tunable parameters for the WiFi driver
 struct Config {
     #[default(5)]
     rx_queue_size: usize,
@@ -174,10 +177,12 @@ pub type EspWifiTimer = hal::timer::Timer<hal::timer::Timer0<hal::peripherals::T
 #[derive(Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
+/// An internal struct designed to make [`EspWifiInitialization`] uncreatable outside of this crate.
 pub struct EspWifiInitializationInternal;
 
 #[derive(Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Initialized the driver for WiFi, Bluetooth or both.
 pub enum EspWifiInitialization {
     #[cfg(feature = "wifi")]
     Wifi(EspWifiInitializationInternal),
@@ -209,6 +214,7 @@ impl EspWifiInitialization {
 
 #[derive(Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Initialize the driver for WiFi, Bluetooth or both.
 pub enum EspWifiInitFor {
     #[cfg(feature = "wifi")]
     Wifi,
@@ -238,8 +244,7 @@ impl EspWifiInitFor {
     }
 }
 
-/// Initialize for using WiFi / BLE
-/// This will initialize internals and also initialize WiFi and BLE
+/// Initialize for using WiFi and or BLE
 pub fn initialize(
     init_for: EspWifiInitFor,
     timer: EspWifiTimer,
@@ -296,7 +301,6 @@ pub fn initialize(
     setup_timer_isr(timer);
     wifi_set_log_verbose();
     init_clocks();
-    init_buffer();
 
     #[cfg(coex)]
     {
@@ -341,6 +345,7 @@ pub fn initialize(
 
 #[derive(Debug, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Error which can be returned during [`initialize`].
 pub enum InitializationError {
     General(i32),
     #[cfg(feature = "wifi")]
@@ -355,6 +360,8 @@ impl From<WifiError> for InitializationError {
     }
 }
 
+/// Enable verbose logging within the WiFi driver
+/// Does nothing unless the `wifi-logs` feature is enabled.
 pub fn wifi_set_log_verbose() {
     #[cfg(feature = "wifi-logs")]
     unsafe {
@@ -365,11 +372,7 @@ pub fn wifi_set_log_verbose() {
     }
 }
 
-pub fn init_buffer() {
-    // nothing anymore for now
-}
-
-pub fn init_clocks() {
+fn init_clocks() {
     unsafe {
         unwrap!(RADIO_CLOCKS.as_mut()).init_clocks();
     }