Merge #869

869: Add some docs. r=Dirbaio a=Dirbaio

bors r+

Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>

embassy-cortex-m/src/interrupt.rs

@@ -211,6 +211,7 @@ const PRIO_MASK: u8 = 0xff;
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
 }
@@ -222,6 +223,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x80,
@@ -234,6 +236,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x40,
@@ -248,6 +251,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x20,
@@ -266,6 +270,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x10,
@@ -292,6 +297,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x8,
@@ -334,6 +340,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x4,
@@ -408,6 +415,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x2,
@@ -546,6 +554,7 @@ pub enum Priority {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum Priority {
     P0 = 0x0,
     P1 = 0x1,

embassy-cortex-m/src/lib.rs

@@ -1,5 +1,6 @@
 //! Embassy executor and interrupt handling specific to cortex-m devices.
 #![no_std]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;

embassy-embedded-hal/src/adapter.rs

@@ -1,9 +1,12 @@
+//! Adapters between embedded-hal traits.
+
 use core::future::Future;
 
 use embedded_hal_02::{blocking, serial};
 
-/// BlockingAsync is a wrapper that implements async traits using blocking peripherals. This allows
-/// driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations.
+/// Wrapper that implements async traits using blocking implementations.
+///
+/// This allows driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations.
 ///
 /// BlockingAsync will implement any async trait that maps to embedded-hal traits implemented for the wrapped driver.
 ///

embassy-embedded-hal/src/lib.rs

@@ -1,12 +1,29 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))]
+#![warn(missing_docs)]
+
+//! Utilities to use `embedded-hal` traits with Embassy.
 
 #[cfg(feature = "nightly")]
 pub mod adapter;
 
 pub mod shared_bus;
 
+/// Set the configuration of a peripheral driver.
+///
+/// This trait is intended to be implemented by peripheral drivers such as SPI
+/// and I2C. It allows changing the configuration at runtime.
+///
+/// The exact type of the "configuration" is defined by each individual driver, since different
+/// drivers support different options. Therefore it is defined as an associated type.
+///
+/// For example, it is used by [`SpiDeviceWithConfig`](crate::shared_bus::asynch::spi::SpiDeviceWithConfig) and
+///  [`I2cDeviceWithConfig`](crate::shared_bus::asynch::i2c::I2cDeviceWithConfig) to allow different
+/// devices on the same bus to use different communication settings.
 pub trait SetConfig {
+    /// The configuration type used by this driver.
     type Config;
+
+    /// Set the configuration of the driver.
     fn set_config(&mut self, config: &Self::Config);
 }

embassy-embedded-hal/src/shared_bus/asynch/i2c.rs

@@ -31,11 +31,13 @@ use embedded_hal_async::i2c;
 use crate::shared_bus::I2cDeviceError;
 use crate::SetConfig;
 
+/// I2C device on a shared bus.
 pub struct I2cDevice<'a, M: RawMutex, BUS> {
     bus: &'a Mutex<M, BUS>,
 }
 
 impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> {
+    /// Create a new `I2cDevice`.
     pub fn new(bus: &'a Mutex<M, BUS>) -> Self {
         Self { bus }
     }
@@ -103,12 +105,18 @@ where
     }
 }
 
+/// I2C device on a shared bus, with its own configuration.
+///
+/// This is like [`I2cDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
 pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> {
     bus: &'a Mutex<M, BUS>,
     config: BUS::Config,
 }
 
 impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
+    /// Create a new `I2cDeviceWithConfig`.
     pub fn new(bus: &'a Mutex<M, BUS>, config: BUS::Config) -> Self {
         Self { bus, config }
     }

embassy-embedded-hal/src/shared_bus/asynch/spi.rs

@@ -36,12 +36,14 @@ use embedded_hal_async::spi;
 use crate::shared_bus::SpiDeviceError;
 use crate::SetConfig;
 
+/// SPI device on a shared bus.
 pub struct SpiDevice<'a, M: RawMutex, BUS, CS> {
     bus: &'a Mutex<M, BUS>,
     cs: CS,
 }
 
 impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> {
+    /// Create a new `SpiDevice`.
     pub fn new(bus: &'a Mutex<M, BUS>, cs: CS) -> Self {
         Self { bus, cs }
     }
@@ -93,6 +95,11 @@ where
     }
 }
 
+/// SPI device on a shared bus, with its own configuration.
+///
+/// This is like [`SpiDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
 pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
     bus: &'a Mutex<M, BUS>,
     cs: CS,
@@ -100,6 +107,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
 }
 
 impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
+    /// Create a new `SpiDeviceWithConfig`.
     pub fn new(bus: &'a Mutex<M, BUS>, cs: CS, config: BUS::Config) -> Self {
         Self { bus, cs, config }
     }

embassy-embedded-hal/src/shared_bus/blocking/i2c.rs

@@ -26,11 +26,13 @@ use embedded_hal_1::i2c::ErrorType;
 use crate::shared_bus::I2cDeviceError;
 use crate::SetConfig;
 
+/// I2C device on a shared bus.
 pub struct I2cDevice<'a, M: RawMutex, BUS> {
     bus: &'a Mutex<M, RefCell<BUS>>,
 }
 
 impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> {
+    /// Create a new `I2cDevice`.
     pub fn new(bus: &'a Mutex<M, RefCell<BUS>>) -> Self {
         Self { bus }
     }
@@ -143,12 +145,18 @@ where
     }
 }
 
+/// I2C device on a shared bus, with its own configuration.
+///
+/// This is like [`I2cDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
 pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> {
     bus: &'a Mutex<M, RefCell<BUS>>,
     config: BUS::Config,
 }
 
 impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
+    /// Create a new `I2cDeviceWithConfig`.
     pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, config: BUS::Config) -> Self {
         Self { bus, config }
     }

embassy-embedded-hal/src/shared_bus/blocking/spi.rs

@@ -29,12 +29,14 @@ use embedded_hal_1::spi::blocking::SpiBusFlush;
 use crate::shared_bus::SpiDeviceError;
 use crate::SetConfig;
 
+/// SPI device on a shared bus.
 pub struct SpiDevice<'a, M: RawMutex, BUS, CS> {
     bus: &'a Mutex<M, RefCell<BUS>>,
     cs: CS,
 }
 
 impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> {
+    /// Create a new `SpiDevice`.
     pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, cs: CS) -> Self {
         Self { bus, cs }
     }
@@ -117,6 +119,11 @@ where
     }
 }
 
+/// SPI device on a shared bus, with its own configuration.
+///
+/// This is like [`SpiDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
 pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
     bus: &'a Mutex<M, RefCell<BUS>>,
     cs: CS,
@@ -124,6 +131,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
 }
 
 impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
+    /// Create a new `SpiDeviceWithConfig`.
     pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, cs: CS, config: BUS::Config) -> Self {
         Self { bus, cs, config }
     }

embassy-embedded-hal/src/shared_bus/mod.rs

@@ -8,8 +8,10 @@ pub mod asynch;
 
 pub mod blocking;
 
+/// Error returned by I2C device implementations in this crate.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum I2cDeviceError<BUS> {
+    /// An operation on the inner I2C bus failed.
     I2c(BUS),
 }
 
@@ -24,9 +26,12 @@ where
     }
 }
 
+/// Error returned by SPI device implementations in this crate.
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum SpiDeviceError<BUS, CS> {
+    /// An operation on the inner SPI bus failed.
     Spi(BUS),
+    /// Setting the value of the Chip Select (CS) pin failed.
     Cs(CS),
 }