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

embassy-nrf/src/buffered_uarte.rs

@@ -3,7 +3,7 @@
 //! WARNING!!! The functionality provided here is intended to be used only
 //! in situations where hardware flow control are available i.e. CTS and RTS.
 //! This is a problem that should be addressed at a later stage and can be
-//! fully explained at https://github.com/embassy-rs/embassy/issues/536.
+//! fully explained at <https://github.com/embassy-rs/embassy/issues/536>.
 //!
 //! Note that discarding a future from a read or write operation may lead to losing
 //! data. For example, when using `futures_util::future::select` and completion occurs

embassy-nrf/src/gpio.rs

@@ -429,7 +429,7 @@ mod eh02 {
         }
     }
 
-    /// Implement [`InputPin`] for [`Flex`];
+    /// Implement [`embedded_hal_02::digital::v2::InputPin`] for [`Flex`];
     ///
     /// If the pin is not in input mode the result is unspecified.
     impl<'d, T: Pin> embedded_hal_02::digital::v2::InputPin for Flex<'d, T> {

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.

embassy-nrf/src/uarte.rs

@@ -19,9 +19,9 @@ use core::task::Poll;
 
 use embassy_hal_common::drop::OnDrop;
 use embassy_hal_common::unborrow;
-use futures::future::poll_fn;
-// Re-export SVD variants to allow user to directly set values.
-pub use pac::uarte0::{baudrate::BAUDRATE_A as Baudrate, config::PARITY_A as Parity};
+use futures::future::poll_fn; // Re-export SVD variants to allow user to directly set values.
+pub use pac::uarte0::baudrate::BAUDRATE_A as Baudrate;
+pub use pac::uarte0::config::PARITY_A as Parity;
 
 use crate::chip::{EASY_DMA_SIZE, FORCE_COPY_BUFFER_SIZE};
 use crate::gpio::sealed::Pin as _;