Merge #918

918: Doc warnings r=Dirbaio a=lulf

Fixing a few doc warnings in embassy-executor, embassy-time, embassy-usb and embassy-nrf. There are more left, but I need a break :D 



Co-authored-by: Ulf Lilleengen <lulf@redhat.com>

embassy-executor/src/raw/mod.rs

@@ -5,7 +5,7 @@
 //! ## WARNING: here be dragons!
 //!
 //! Using this module requires respecting subtle safety contracts. If you can, prefer using the safe
-//! executor wrappers in [`executor`](crate::executor) and the [`embassy_executor::task`](embassy_macros::task) macro, which are fully safe.
+//! [executor wrappers](crate::Executor) and the [`embassy_executor::task`](embassy_macros::task) macro, which are fully safe.
 
 mod run_queue;
 #[cfg(feature = "integrated-timers")]
@@ -249,7 +249,7 @@ impl<F: Future + 'static, const N: usize> TaskPool<F, N> {
 ///
 /// This is the core of the Embassy executor. It is low-level, requiring manual
 /// handling of wakeups and task polling. If you can, prefer using one of the
-/// higher level executors in [`crate::executor`].
+/// [higher level executors](crate::Executor).
 ///
 /// The raw executor leaves it up to you to handle wakeups and scheduling:
 ///

embassy-nrf/src/buffered_uarte.rs

@@ -45,8 +45,10 @@ enum TxState {
     Transmitting(usize),
 }
 
+/// A type for storing the state of the UARTE peripheral that can be stored in a static.
 pub struct State<'d, U: UarteInstance, T: TimerInstance>(StateStorage<StateInner<'d, U, T>>);
 impl<'d, U: UarteInstance, T: TimerInstance> State<'d, U, T> {
+    /// Create an instance for storing UARTE peripheral state.
     pub fn new() -> Self {
         Self(StateStorage::new())
     }
@@ -75,6 +77,12 @@ pub struct BufferedUarte<'d, U: UarteInstance, T: TimerInstance> {
 impl<'d, U: UarteInstance, T: TimerInstance> Unpin for BufferedUarte<'d, U, T> {}
 
 impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
+    /// Create a new instance of a BufferedUarte.
+    ///
+    /// See the [module documentation](crate::buffered_uarte) for more details about the intended use.
+    ///
+    /// The BufferedUarte uses the provided state to store the buffers and peripheral state. The timer and ppi channels are used to 'emulate' idle line detection so that read operations
+    /// can return early if there is no data to receive.
     pub fn new(
         state: &'d mut State<'d, U, T>,
         peri: impl Peripheral<P = U> + 'd,
@@ -178,6 +186,7 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
         }
     }
 
+    /// Adjust the baud rate to the provided value.
     pub fn set_baudrate(&mut self, baudrate: Baudrate) {
         self.inner.with(|state| {
             let r = U::regs();

embassy-nrf/src/gpio.rs

@@ -1,3 +1,4 @@
+//! General purpose input/output for nRF.
 #![macro_use]
 
 use core::convert::Infallible;
@@ -26,8 +27,11 @@ pub enum Port {
 #[derive(Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Pull {
+    /// No pull.
     None,
+    /// Internal pull-up resistor.
     Up,
+    /// Internal pull-down resistor.
     Down,
 }
 
@@ -37,6 +41,7 @@ pub struct Input<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> Input<'d, T> {
+    /// Create GPIO input driver for a [Pin] with the provided [Pull] configuration.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, pull: Pull) -> Self {
         let mut pin = Flex::new(pin);
@@ -45,11 +50,13 @@ impl<'d, T: Pin> Input<'d, T> {
         Self { pin }
     }
 
+    /// Test if current pin level is high.
     #[inline]
     pub fn is_high(&self) -> bool {
         self.pin.is_high()
     }
 
+    /// Test if current pin level is low.
     #[inline]
     pub fn is_low(&self) -> bool {
         self.pin.is_low()
@@ -66,7 +73,9 @@ impl<'d, T: Pin> Input<'d, T> {
 #[derive(Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Level {
+    /// Logical low.
     Low,
+    /// Logical high.
     High,
 }
 
@@ -88,6 +97,7 @@ impl Into<bool> for Level {
     }
 }
 
+/// Drive strength settings for an output pin.
 // These numbers match DRIVE_A exactly so hopefully the compiler will unify them.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -117,6 +127,7 @@ pub struct Output<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> Output<'d, T> {
+    /// Create GPIO output driver for a [Pin] with the provided [Level] and [OutputDriver] configuration.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level, drive: OutputDrive) -> Self {
         let mut pin = Flex::new(pin);
@@ -264,11 +275,13 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.conf().reset();
     }
 
+    /// Test if current pin level is high.
     #[inline]
     pub fn is_high(&self) -> bool {
         !self.is_low()
     }
 
+    /// Test if current pin level is low.
     #[inline]
     pub fn is_low(&self) -> bool {
         self.pin.block().in_.read().bits() & (1 << self.pin.pin()) == 0
@@ -374,6 +387,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// Interface for a Pin that can be configured by an [Input] or [Output] driver, or converted to an [AnyPin].
 pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'static {
     /// Number of the pin within the port (0..31)
     #[inline]
@@ -392,6 +406,7 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
         }
     }
 
+    /// Peripheral port register value
     #[inline]
     fn psel_bits(&self) -> u32 {
         self.pin_port() as u32
@@ -406,12 +421,16 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
     }
 }
 
-// Type-erased GPIO pin
+/// Type-erased GPIO pin
 pub struct AnyPin {
     pin_port: u8,
 }
 
 impl AnyPin {
+    /// Create an [AnyPin] for a specific pin.
+    ///
+    /// # Safety
+    /// - `pin_port` should not in use by another driver.
     #[inline]
     pub unsafe fn steal(pin_port: u8) -> Self {
         Self { pin_port }

embassy-nrf/src/nvmc.rs

@@ -1,4 +1,4 @@
-//! Nvmcerature sensor interface.
+//! Non-Volatile Memory Controller (NVMC) module.
 
 use core::{ptr, slice};
 
@@ -10,13 +10,19 @@ use embedded_storage::nor_flash::{
 use crate::peripherals::NVMC;
 use crate::{pac, Peripheral};
 
+/// Erase size of NVMC flash in bytes.
 pub const PAGE_SIZE: usize = 4096;
+
+/// Size of NVMC flash in bytes.
 pub const FLASH_SIZE: usize = crate::chip::FLASH_SIZE;
 
+/// Error type for NVMC operations.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Opration using a location not in flash.
     OutOfBounds,
+    /// Unaligned operation or using unaligned buffers.
     Unaligned,
 }
 
@@ -29,11 +35,13 @@ impl NorFlashError for Error {
     }
 }
 
+/// Non-Volatile Memory Controller (NVMC) that implements the `embedded-storage` traits.
 pub struct Nvmc<'d> {
     _p: PeripheralRef<'d, NVMC>,
 }
 
 impl<'d> Nvmc<'d> {
+    /// Create Nvmc driver.
     pub fn new(_p: impl Peripheral<P = NVMC> + 'd) -> Self {
         into_ref!(_p);
         Self { _p }

embassy-nrf/src/ppi/mod.rs

@@ -26,6 +26,7 @@ mod dppi;
 #[cfg(feature = "_ppi")]
 mod ppi;
 
+/// An instance of the Programmable peripheral interconnect on nRF devices.
 pub struct Ppi<'d, C: Channel, const EVENT_COUNT: usize, const TASK_COUNT: usize> {
     ch: PeripheralRef<'d, C>,
     #[cfg(feature = "_dppi")]
@@ -48,6 +49,7 @@ impl Task {
         Self(unsafe { NonNull::new_unchecked(reg as *const _ as *mut _) })
     }
 
+    /// Address off subscription register for this task.
     pub fn subscribe_reg(&self) -> *mut u32 {
         unsafe { self.0.as_ptr().add(REGISTER_DPPI_CONFIG_OFFSET) }
     }
@@ -69,6 +71,7 @@ impl Event {
         Self(unsafe { NonNull::new_unchecked(reg as *const _ as *mut _) })
     }
 
+    /// Address of publish register for this event.
     pub fn publish_reg(&self) -> *mut u32 {
         unsafe { self.0.as_ptr().add(REGISTER_DPPI_CONFIG_OFFSET) }
     }
@@ -87,21 +90,29 @@ pub(crate) mod sealed {
     pub trait Group {}
 }
 
+/// Interface for PPI channels.
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + Sized {
     /// Returns the number of the channel
     fn number(&self) -> usize;
 }
 
+/// Interface for PPI channels that can be configured.
 pub trait ConfigurableChannel: Channel + Into<AnyConfigurableChannel> {
+    /// Convert into a type erased configurable channel.
     fn degrade(self) -> AnyConfigurableChannel;
 }
 
+/// Interface for PPI channels that cannot be configured.
 pub trait StaticChannel: Channel + Into<AnyStaticChannel> {
+    /// Convert into a type erased static channel.
     fn degrade(self) -> AnyStaticChannel;
 }
 
+/// Interface for a group of PPI channels.
 pub trait Group: sealed::Group + Sized {
+    /// Returns the number of the group.
     fn number(&self) -> usize;
+    /// Convert into a type erased group.
     fn degrade(self) -> AnyGroup {
         AnyGroup {
             number: self.number() as u8,
@@ -196,6 +207,7 @@ macro_rules! impl_ppi_channel {
 // ======================
 //       groups
 
+/// A type erased PPI group.
 pub struct AnyGroup {
     number: u8,
 }

embassy-nrf/src/ppi/ppi.rs

@@ -20,6 +20,7 @@ fn regs() -> &'static pac::ppi::RegisterBlock {
 
 #[cfg(not(feature = "nrf51"))] // Not for nrf51 because of the fork task
 impl<'d, C: StaticChannel> Ppi<'d, C, 0, 1> {
+    /// Configure PPI channel to trigger `task`.
     pub fn new_zero_to_one(ch: impl Peripheral<P = C> + 'd, task: Task) -> Self {
         into_ref!(ch);
 
@@ -32,6 +33,7 @@ impl<'d, C: StaticChannel> Ppi<'d, C, 0, 1> {
 }
 
 impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 1> {
+    /// Configure PPI channel to trigger `task` on `event`.
     pub fn new_one_to_one(ch: impl Peripheral<P = C> + 'd, event: Event, task: Task) -> Self {
         into_ref!(ch);
 
@@ -46,6 +48,7 @@ impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 1> {
 
 #[cfg(not(feature = "nrf51"))] // Not for nrf51 because of the fork task
 impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 2> {
+    /// Configure PPI channel to trigger `task1` and `task2` on `event`.
     pub fn new_one_to_two(ch: impl Peripheral<P = C> + 'd, event: Event, task1: Task, task2: Task) -> Self {
         into_ref!(ch);
 

embassy-time/src/driver.rs

@@ -6,7 +6,7 @@
 //!
 //! - Define a struct `MyDriver`
 //! - Implement [`Driver`] for it
-//! - Register it as the global driver with [`time_driver_impl`].
+//! - Register it as the global driver with [`time_driver_impl`](crate::time_driver_impl).
 //! - Enable the Cargo features `embassy-executor/time` and one of `embassy-time/tick-*` corresponding to the
 //!   tick rate of your driver.
 //!

embassy-usb/src/builder.rs

@@ -10,6 +10,7 @@ use crate::{Interface, STRING_INDEX_CUSTOM_START};
 #[derive(Debug, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
+/// Configuration used when creating [UsbDevice].
 pub struct Config<'a> {
     pub(crate) vendor_id: u16,
     pub(crate) product_id: u16,
@@ -96,6 +97,7 @@ pub struct Config<'a> {
 }
 
 impl<'a> Config<'a> {
+    /// Create default configuration with the provided vid and pid values.
     pub fn new(vid: u16, pid: u16) -> Self {
         Self {
             device_class: 0x00,

embassy-usb/src/control.rs

@@ -1,3 +1,4 @@
+//! USB control data types.
 use core::mem;
 
 use super::types::*;
@@ -8,7 +9,7 @@ use super::types::*;
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum RequestType {
     /// Request is a USB standard request. Usually handled by
-    /// [`UsbDevice`](crate::device::UsbDevice).
+    /// [`UsbDevice`](crate::UsbDevice).
     Standard = 0,
     /// Request is intended for a USB class.
     Class = 1,

embassy-usb/src/driver.rs

@@ -12,7 +12,7 @@ pub trait Driver<'a> {
 
     /// Allocates an endpoint and specified endpoint parameters. This method is called by the device
     /// and class implementations to allocate endpoints, and can only be called before
-    /// [`start`](UsbBus::start) is called.
+    /// [`start`](Self::start) is called.
     ///
     /// # Arguments
     ///
@@ -95,7 +95,7 @@ pub trait Bus {
     ///
     /// # Errors
     ///
-    /// * [`Unsupported`](crate::UsbError::Unsupported) - This UsbBus implementation doesn't support
+    /// * [`Unsupported`](crate::driver::Unsupported) - This UsbBus implementation doesn't support
     ///   simulating a disconnect or it has not been enabled at creation time.
     fn force_reset(&mut self) -> Result<(), Unsupported> {
         Err(Unsupported)
@@ -105,7 +105,7 @@ pub trait Bus {
     ///
     /// # Errors
     ///
-    /// * [`Unsupported`](crate::UsbError::Unsupported) - This UsbBus implementation doesn't support
+    /// * [`Unsupported`](crate::driver::Unsupported) - This UsbBus implementation doesn't support
     ///   remote wakeup or it has not been enabled at creation time.
     fn remote_wakeup(&mut self) -> Self::RemoteWakeupFuture<'_>;
 }