From d2f4a9bf8df8de9f51b29659b464b4509af47dc6 Mon Sep 17 00:00:00 2001
From: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Date: Tue, 19 Jul 2022 07:57:39 +0200
Subject: embassy-embedded-hal: docs

---
 embassy-embedded-hal/src/shared_bus/asynch/i2c.rs   | 8 ++++++++
 embassy-embedded-hal/src/shared_bus/asynch/spi.rs   | 8 ++++++++
 embassy-embedded-hal/src/shared_bus/blocking/i2c.rs | 8 ++++++++
 embassy-embedded-hal/src/shared_bus/blocking/spi.rs | 8 ++++++++
 embassy-embedded-hal/src/shared_bus/mod.rs          | 5 +++++
 5 files changed, 37 insertions(+)

(limited to 'embassy-embedded-hal/src/shared_bus')

diff --git a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
index 5bd3d9bc5..fa77a06d3 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
+++ b/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 }
     }
diff --git a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
index 343184d12..a08eaa82d 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
+++ b/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 }
     }
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
index 1ec480c0c..c8b5e30f6 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
+++ b/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 }
     }
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
index ff92e1a7e..d0648f59a 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
+++ b/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 }
     }
diff --git a/embassy-embedded-hal/src/shared_bus/mod.rs b/embassy-embedded-hal/src/shared_bus/mod.rs
index 3cd380f72..76ee413d9 100644
--- a/embassy-embedded-hal/src/shared_bus/mod.rs
+++ b/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),
 }
 
-- 
cgit