Add more API docs for embassy-cortex-m and embassy-nrf

embassy-nrf/src/lib.rs

@@ -1,3 +1,11 @@
+//! # Embassy nRF HAL
+//!
+//! HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed.
+//!
+//! The Embassy nRF HAL targets the Nordic Semiconductor nRF family of hardware. The HAL implements both blocking and async APIs
+//! for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
+//! complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
+//!
 //! ## EasyDMA considerations
 //!
 //! On nRF chips, peripherals can use the so called EasyDMA feature to offload the task of interacting
@@ -23,8 +31,8 @@
 //! ```
 //!
 //! Each peripheral struct which uses EasyDMA ([`Spim`](spim::Spim), [`Uarte`](uarte::Uarte), [`Twim`](twim::Twim)) has two variants of their mutating functions:
-//! - Functions with the suffix (e.g. [`write_from_ram`](Spim::write_from_ram), [`transfer_from_ram`](Spim::transfer_from_ram)) will return an error if the passed slice does not reside in RAM.
-//! - Functions without the suffix (e.g. [`write`](Spim::write), [`transfer`](Spim::transfer)) will check whether the data is in RAM and copy it into memory prior to transmission.
+//! - Functions with the suffix (e.g. [`write_from_ram`](spim::Spim::write_from_ram), [`transfer_from_ram`](spim::Spim::transfer_from_ram)) will return an error if the passed slice does not reside in RAM.
+//! - Functions without the suffix (e.g. [`write`](spim::Spim::write), [`transfer`](spim::Spim::transfer)) will check whether the data is in RAM and copy it into memory prior to transmission.
 //!
 //! Since copying incurs a overhead, you are given the option to choose from `_from_ram` variants which will
 //! fail and notify you, or the more convenient versions without the suffix which are potentially a little bit
@@ -112,6 +120,7 @@ mod chip;
 pub use chip::EASY_DMA_SIZE;
 
 pub mod interrupt {
+    //! nRF interrupts for cortex-m devices.
     pub use cortex_m::interrupt::{CriticalSection, Mutex};
     pub use embassy_cortex_m::interrupt::*;
 
@@ -130,28 +139,44 @@ pub use embassy_hal_common::{unborrow, Unborrow};
 pub use embassy_macros::cortex_m_interrupt as interrupt;
 
 pub mod config {
+    //! Configuration options used when initializing the HAL.
+
+    /// High frequency clock source.
     pub enum HfclkSource {
+        /// Internal source
         Internal,
+        /// External source from xtal.
         ExternalXtal,
     }
 
+    /// Low frequency clock source
     pub enum LfclkSource {
+        /// Internal RC oscillator
         InternalRC,
+        /// Synthesized from the high frequency clock source.
         #[cfg(not(any(feature = "_nrf5340", feature = "_nrf9160")))]
         Synthesized,
+        /// External source from xtal.
         ExternalXtal,
+        /// External source from xtal with low swing applied.
         #[cfg(not(any(feature = "_nrf5340", feature = "_nrf9160")))]
         ExternalLowSwing,
+        /// External source from xtal with full swing applied.
         #[cfg(not(any(feature = "_nrf5340", feature = "_nrf9160")))]
         ExternalFullSwing,
     }
 
+    /// Configuration for peripherals. Default configuration should work on any nRF chip.
     #[non_exhaustive]
     pub struct Config {
+        /// High frequency clock source.
         pub hfclk_source: HfclkSource,
+        /// Low frequency clock source.
         pub lfclk_source: LfclkSource,
+        /// GPIOTE interrupt priority. Should be lower priority than softdevice if used.
         #[cfg(feature = "gpiote")]
         pub gpiote_interrupt_priority: crate::interrupt::Priority,
+        /// Time driver interrupt priority. Should be lower priority than softdevice if used.
         #[cfg(feature = "_time-driver")]
         pub time_interrupt_priority: crate::interrupt::Priority,
     }
@@ -173,6 +198,7 @@ pub mod config {
     }
 }
 
+/// Initialize peripherals with the provided configuration. This should only be called once at startup.
 pub fn init(config: config::Config) -> Peripherals {
     // Do this first, so that it panics if user is calling `init` a second time
     // before doing anything important.