Add more docs

embassy-stm32/src/i2c/config.rs

@@ -5,14 +5,23 @@ use crate::gpio::Pull;
 #[repr(u8)]
 #[derive(Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Bits of the I2C OA2 register to mask out.
 pub enum AddrMask {
+    /// No mask
     NOMASK,
+    /// OA2\[1\] is masked and don’t care. Only OA2\[7:2\] are compared.
     MASK1,
+    /// OA2\[2:1\] are masked and don’t care. Only OA2\[7:3\] are compared.
     MASK2,
+    /// OA2\[3:1\] are masked and don’t care. Only OA2\[7:4\] are compared.
     MASK3,
+    /// OA2\[4:1\] are masked and don’t care. Only OA2\[7:5\] are compared.
     MASK4,
+    /// OA2\[5:1\] are masked and don’t care. Only OA2\[7:6\] are compared.
     MASK5,
+    /// OA2\[6:1\] are masked and don’t care. Only OA2\[7:6\] are compared.
     MASK6,
+    /// OA2\[7:1\] are masked and don’t care. No comparison is done, and all (except reserved) 7-bit received addresses are acknowledged
     MASK7,
 }
 impl From<AddrMask> for Oamsk {
@@ -32,8 +41,13 @@ impl From<AddrMask> for Oamsk {
 
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// An I2C address. Either 7 or 10 bit.
 pub enum Address {
+    /// A 7 bit address
     SevenBit(u8),
+    /// A 10 bit address.
+    ///
+    /// When using an address to configure the Own Address, only the OA1 register can be set to a 10-bit address.
     TenBit(u16),
 }
 impl From<u8> for Address {
@@ -54,6 +68,9 @@ impl Address {
             Address::TenBit(_) => stm32_metapac::i2c::vals::Addmode::BIT10,
         }
     }
+    /// Get the inner address as a u16.
+    ///
+    /// For 7 bit addresses, the u8 that was used to store the address is returned as a u16.
     pub fn addr(&self) -> u16 {
         match self {
             Address::SevenBit(addr) => *addr as u16,
@@ -64,17 +81,29 @@ impl Address {
 
 #[derive(Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// The second Own Address register.
 pub struct OA2 {
+    /// The address.
     pub addr: u8,
+    /// The bit mask that will affect how the own address 2 register is compared.
     pub mask: AddrMask,
 }
 
 #[derive(Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// The Own Address(es) of the I2C peripheral.
 pub enum OwnAddresses {
+    /// Configuration for only the OA1 register.
     OA1(Address),
+    /// Configuration for only the OA2 register.
     OA2(OA2),
-    Both { oa1: Address, oa2: OA2 },
+    /// Configuration for both the OA1 and OA2 registers.
+    Both {
+        /// The [Address] for the OA1 register.
+        oa1: Address,
+        /// The [OA2] configuration.
+        oa2: OA2,
+    },
 }
 
 /// Slave Configuration
@@ -87,16 +116,10 @@ pub struct SlaveAddrConfig {
     pub general_call: bool,
 }
 impl SlaveAddrConfig {
-    pub fn new_oa1(addr: Address, general_call: bool) -> Self {
+    /// Create a new slave address configuration with only the OA1 register set in 7 bit mode and the general call disabled.
+    pub fn basic(addr: u8) -> Self {
         Self {
-            addr: OwnAddresses::OA1(addr),
-            general_call,
-        }
-    }
-
-    pub fn basic(addr: Address) -> Self {
-        Self {
-            addr: OwnAddresses::OA1(addr),
+            addr: OwnAddresses::OA1(Address::SevenBit(addr)),
             general_call: false,
         }
     }

embassy-stm32/src/i2c/mod.rs

@@ -16,7 +16,7 @@ use embassy_hal_internal::{Peripheral, PeripheralRef};
 use embassy_sync::waitqueue::AtomicWaker;
 #[cfg(feature = "time")]
 use embassy_time::{Duration, Instant};
-use mode::{Master, MasterMode, MultiMaster};
+use mode::{Master, MasterMode};
 
 use crate::dma::ChannelAndRequest;
 #[cfg(gpio_v2)]
@@ -146,7 +146,9 @@ pub enum CommandKind {
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 /// The command kind to the slave from the master and the address that the slave matched
 pub struct Command {
+    /// The kind of command
     pub kind: CommandKind,
+    /// The address that the slave matched
     pub address: Address,
 }
 

embassy-stm32/src/i2c/v2.rs

@@ -6,7 +6,7 @@ use config::{Address, OwnAddresses, OA2};
 use embassy_embedded_hal::SetConfig;
 use embassy_hal_internal::drop::OnDrop;
 use embedded_hal_1::i2c::Operation;
-use mode::Master;
+use mode::{Master, MultiMaster};
 use stm32_metapac::i2c::vals::Addmode;
 
 use super::*;