PeripheralRef docs improvements.

1 files changed, 10 insertions, 9 deletions

diff --git a/embassy-hal-common/src/peripheral.rs b/embassy-hal-common/src/peripheral.rs
index f507468f8..4a6b6a600 100644
--- a/embassy-hal-common/src/peripheral.rs
+++ b/embassy-hal-common/src/peripheral.rs
@@ -3,16 +3,17 @@ use core::ops::{Deref, DerefMut};
 
 /// An exclusive reference to a peripheral.
 ///
-/// This is functionally the same as a `&'a mut T`. The reason for having a
-/// dedicated struct is memory efficiency:
+/// This is functionally the same as a `&'a mut T`. There's a few advantages in having
+/// a dedicated struct instead:
 ///
-/// Peripheral singletons are typically either zero-sized (for concrete peripherals
-/// like `PA9` or `Spi4`) or very small (for example `AnyPin` which is 1 byte).
-/// However `&mut T` is always 4 bytes for 32-bit targets, even if T is zero-sized.
-/// PeripheralRef stores a copy of `T` instead, so it's the same size.
-///
-/// but it is the size of `T` not the size
-/// of a pointer. This is useful if T is a zero sized type.
+/// - Memory efficiency: Peripheral singletons are typically either zero-sized (for concrete
+///   peripherals like `PA9` or `SPI4`) or very small (for example `AnyPin`, which is 1 byte).
+///   However `&mut T` is always 4 bytes for 32-bit targets, even if T is zero-sized.
+///   PeripheralRef stores a copy of `T` instead, so it's the same size.
+/// - Code size efficiency. If the user uses the same driver with both `SPI4` and `&mut SPI4`,
+///   the driver code would be monomorphized two times. With PeripheralRef, the driver is generic
+///   over a lifetime only. `SPI4` becomes `PeripheralRef<'static, SPI4>`, and `&mut SPI4` becomes
+///   `PeripheralRef<'a, SPI4>`. Lifetimes don't cause monomorphization.
 pub struct PeripheralRef<'a, T> {
     inner: T,
     _lifetime: PhantomData<&'a mut T>,