Apply suggestions from code review

Co-authored-by: Diego Barrios Romero <[email protected]>

Author: ryankurte

src/blocking/spi.rs

@@ -38,17 +38,17 @@ pub trait WriteIter<W> {
         WI: IntoIterator<Item = W>;
 }
 
-/// ManagedCS marker trait indicates the CS pin is managed by the underlying driver.
+/// `ManagedCs` marker trait indicates the chip-select (CS) pin is managed by the underlying driver.
 ///
-/// This specifies that all `spi` operations will be preceded by asserting the CS pin,
+/// This specifies that all SPI operations will be preceded by asserting the CS pin,
 /// and followed by de-asserting the CS pin, prior to returning from the method.
 ///
 /// This is important for shared bus access to ensure that only one CS can be asserted
 /// at a given time. Drivers should require this (and not manage their own CS pins)
 /// in order to support shared use.
 ///
 /// To chain operations within one transaction see [Transactional].
-/// For or a convenience wrapper defining this type for non-shared / exclusive use
+/// For a convenience wrapper defining this type for non-shared / exclusive use
 /// see [`SpiWithCs`](spi_with_cs::SpiWithCs).
 pub trait ManagedCs {}
 
@@ -66,7 +66,7 @@ pub enum Operation<'a, W: 'static> {
 /// Transactional trait allows multiple actions to be executed
 /// as part of a single SPI transaction.
 ///
-/// This API guarantees ordering, ensuring operations from
+/// This API guarantees grouping, ensuring operations from
 /// different sources will not be interleaved on a shared bus.
 /// [ManagedCs]
 pub trait Transactional<W: 'static> {
@@ -106,7 +106,7 @@ pub mod spi_with_cs {
         Pin(PinError),
     }
 
-    /// ManagedCS marker trait indicates Chip Select management is automatic
+    /// `ManagedCs` marker trait indicates chip-select management is automatic
     impl<Spi, SpiError, Pin, PinError> ManagedCs for SpiWithCs<Spi, SpiError, Pin, PinError> {}
 
     impl<Spi, SpiError, Pin, PinError> SpiWithCs<Spi, SpiError, Pin, PinError>
@@ -115,7 +115,7 @@ pub mod spi_with_cs {
         SpiError: Debug,
         PinError: Debug,
     {
-        /// Create a new SpiWithCS wrapper with the provided Spi and Pin
+        /// Create a new `SpiWithCs` wrapper with the provided SPI bus and Pin
         pub fn new(spi: Spi, cs: Pin) -> Self {
             Self {
                 spi,
@@ -125,13 +125,14 @@ pub mod spi_with_cs {
             }
         }
 
-        /// Fetch references to the inner Spi and Pin types.
+        /// Fetch references to the inner SPI bus and Pin types
+        ///
         /// Note that using these directly will violate the `ManagedCs` constraint.
         pub fn inner(&mut self) -> (&mut Spi, &mut Pin) {
             (&mut self.spi, &mut self.cs)
         }
 
-        /// Destroy the SpiWithCs wrapper, returning the bus and pin objects
+        /// Destroy the `SpiWithCs` wrapper, returning the SPI bus and Pin objects
         pub fn destroy(self) -> (Spi, Pin) {
             (self.spi, self.cs)
         }
@@ -157,7 +158,7 @@ pub mod spi_with_cs {
             // Deassert CS
             self.cs.set_high().map_err(SpiWithCsError::Pin)?;
 
-            // Return failures
+            // Return transfer result or failure
             spi_result
         }
     }
@@ -182,7 +183,7 @@ pub mod spi_with_cs {
             // Deassert CS
             self.cs.set_high().map_err(SpiWithCsError::Pin)?;
 
-            // Return failures
+            // Return transfer result or failure
             spi_result
         }
     }
@@ -210,7 +211,7 @@ pub mod spi_with_cs {
             // Deassert CS
             self.cs.set_high().map_err(SpiWithCsError::Pin)?;
 
-            // Return failures
+            // Return transfer result or failure
             spi_result
         }
     }