e-h: amend documents to add periods (.), add inline hints when necessary

In documentation style of the Rust standard library, first sentence of all
modules, types, and functions documentation has a period. We follow Rust
standard library style to make it easier for users to read.

All functions in embedded-hal (especially type conversations, function
fowarding calls) are now marked #[inline] to allow further optimizations.

Signed-off-by: Zhouqi Jiang <[email protected]>

Author: luojia65

embedded-hal/src/delay.rs

@@ -1,14 +1,14 @@
-//! Delays
+//! Delays.
 
-/// Microsecond delay
-///
+/// Microsecond delay.
 pub trait DelayUs {
     /// Pauses execution for at minimum `us` microseconds. Pause can be longer
     /// if the implementation requires it due to precision/timing issues.
     fn delay_us(&mut self, us: u32);
 
     /// Pauses execution for at minimum `ms` milliseconds. Pause can be longer
     /// if the implementation requires it due to precision/timing issues.
+    #[inline]
     fn delay_ms(&mut self, ms: u32) {
         for _ in 0..ms {
             self.delay_us(1000);
@@ -20,10 +20,12 @@ impl<T> DelayUs for &mut T
 where
     T: DelayUs + ?Sized,
 {
+    #[inline]
     fn delay_us(&mut self, us: u32) {
         T::delay_us(self, us)
     }
 
+    #[inline]
     fn delay_ms(&mut self, ms: u32) {
         T::delay_ms(self, ms)
     }

embedded-hal/src/digital.rs

@@ -1,11 +1,11 @@
-//! Digital I/O
+//! Digital I/O.
 
 use core::{convert::From, ops::Not};
 
 #[cfg(feature = "defmt-03")]
 use crate::defmt;
 
-/// Error
+/// Error.
 pub trait Error: core::fmt::Debug {
     /// Convert error to a generic error kind
     ///
@@ -21,7 +21,7 @@ impl Error for core::convert::Infallible {
     }
 }
 
-/// Error kind
+/// Error kind.
 ///
 /// This represents a common set of operation errors. HAL implementations are
 /// free to define more specific or additional error types. However, by providing
@@ -35,12 +35,14 @@ pub enum ErrorKind {
 }
 
 impl Error for ErrorKind {
+    #[inline]
     fn kind(&self) -> ErrorKind {
         *self
     }
 }
 
 impl core::fmt::Display for ErrorKind {
+    #[inline]
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             Self::Other => write!(
@@ -51,7 +53,7 @@ impl core::fmt::Display for ErrorKind {
     }
 }
 
-/// Error type trait
+/// Error type trait.
 ///
 /// This just defines the error type, to be used by the other traits.
 pub trait ErrorType {
@@ -67,7 +69,7 @@ impl<T: ErrorType + ?Sized> ErrorType for &mut T {
     type Error = T::Error;
 }
 
-/// Digital output pin state
+/// Digital output pin state.
 ///
 /// Conversion from `bool` and logical negation are also implemented
 /// for this type.
@@ -80,9 +82,9 @@ impl<T: ErrorType + ?Sized> ErrorType for &mut T {
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 #[cfg_attr(feature = "defmt-03", derive(defmt::Format))]
 pub enum PinState {
-    /// Low pin state
+    /// Low pin state.
     Low,
-    /// High pin state
+    /// High pin state.
     High,
 }
 
@@ -118,24 +120,25 @@ impl From<PinState> for bool {
     }
 }
 
-/// Single digital push-pull output pin
+/// Single digital push-pull output pin.
 pub trait OutputPin: ErrorType {
-    /// Drives the pin low
+    /// Drives the pin low.
     ///
     /// *NOTE* the actual electrical state of the pin may not actually be low, e.g. due to external
-    /// electrical sources
+    /// electrical sources.
     fn set_low(&mut self) -> Result<(), Self::Error>;
 
-    /// Drives the pin high
+    /// Drives the pin high.
     ///
     /// *NOTE* the actual electrical state of the pin may not actually be high, e.g. due to external
-    /// electrical sources
+    /// electrical sources.
     fn set_high(&mut self) -> Result<(), Self::Error>;
 
-    /// Drives the pin high or low depending on the provided value
+    /// Drives the pin high or low depending on the provided value.
     ///
     /// *NOTE* the actual electrical state of the pin may not actually be high or low, e.g. due to external
-    /// electrical sources
+    /// electrical sources.
+    #[inline]
     fn set_state(&mut self, state: PinState) -> Result<(), Self::Error> {
         match state {
             PinState::Low => self.set_low(),
@@ -145,55 +148,61 @@ pub trait OutputPin: ErrorType {
 }
 
 impl<T: OutputPin + ?Sized> OutputPin for &mut T {
+    #[inline]
     fn set_low(&mut self) -> Result<(), Self::Error> {
         T::set_low(self)
     }
 
+    #[inline]
     fn set_high(&mut self) -> Result<(), Self::Error> {
         T::set_high(self)
     }
 
+    #[inline]
     fn set_state(&mut self, state: PinState) -> Result<(), Self::Error> {
         T::set_state(self, state)
     }
 }
 
-/// Push-pull output pin that can read its output state
+/// Push-pull output pin that can read its output state.
 pub trait StatefulOutputPin: OutputPin {
     /// Is the pin in drive high mode?
     ///
-    /// *NOTE* this does *not* read the electrical state of the pin
+    /// *NOTE* this does *not* read the electrical state of the pin.
     fn is_set_high(&self) -> Result<bool, Self::Error>;
 
     /// Is the pin in drive low mode?
     ///
-    /// *NOTE* this does *not* read the electrical state of the pin
+    /// *NOTE* this does *not* read the electrical state of the pin.
     fn is_set_low(&self) -> Result<bool, Self::Error>;
 }
 
 impl<T: StatefulOutputPin + ?Sized> StatefulOutputPin for &mut T {
+    #[inline]
     fn is_set_high(&self) -> Result<bool, Self::Error> {
         T::is_set_high(self)
     }
 
+    #[inline]
     fn is_set_low(&self) -> Result<bool, Self::Error> {
         T::is_set_low(self)
     }
 }
 
-/// Output pin that can be toggled
+/// Output pin that can be toggled.
 pub trait ToggleableOutputPin: ErrorType {
     /// Toggle pin output.
     fn toggle(&mut self) -> Result<(), Self::Error>;
 }
 
 impl<T: ToggleableOutputPin + ?Sized> ToggleableOutputPin for &mut T {
+    #[inline]
     fn toggle(&mut self) -> Result<(), Self::Error> {
         T::toggle(self)
     }
 }
 
-/// Single digital input pin
+/// Single digital input pin.
 pub trait InputPin: ErrorType {
     /// Is the input pin high?
     fn is_high(&self) -> Result<bool, Self::Error>;
@@ -203,10 +212,12 @@ pub trait InputPin: ErrorType {
 }
 
 impl<T: InputPin + ?Sized> InputPin for &T {
+    #[inline]
     fn is_high(&self) -> Result<bool, Self::Error> {
         T::is_high(self)
     }
 
+    #[inline]
     fn is_low(&self) -> Result<bool, Self::Error> {
         T::is_low(self)
     }

embedded-hal/src/i2c.rs

@@ -1,4 +1,4 @@
-//! Blocking I2C API
+//! Blocking I2C API.
 //!
 //! This API supports 7-bit and 10-bit addresses. Traits feature an [`AddressMode`]
 //! marker type parameter. Two implementation of the [`AddressMode`] exist:
@@ -157,9 +157,9 @@ use crate::private;
 #[cfg(feature = "defmt-03")]
 use crate::defmt;
 
-/// I2C error
+/// I2C error.
 pub trait Error: core::fmt::Debug {
-    /// Convert error to a generic I2C error kind
+    /// Convert error to a generic I2C error kind.
     ///
     /// By using this method, I2C errors freely defined by HAL implementations
     /// can be converted to a set of generic I2C errors upon which generic
@@ -168,12 +168,13 @@ pub trait Error: core::fmt::Debug {
 }
 
 impl Error for core::convert::Infallible {
+    #[inline]
     fn kind(&self) -> ErrorKind {
         match *self {}
     }
 }
 
-/// I2C error kind
+/// I2C error kind.
 ///
 /// This represents a common set of I2C operation errors. HAL implementations are
 /// free to define more specific or additional error types. However, by providing
@@ -185,19 +186,19 @@ pub enum ErrorKind {
     /// Bus error occurred. e.g. A START or a STOP condition is detected and is not
     /// located after a multiple of 9 SCL clock pulses.
     Bus,
-    /// The arbitration was lost, e.g. electrical problems with the clock signal
+    /// The arbitration was lost, e.g. electrical problems with the clock signal.
     ArbitrationLoss,
     /// A bus operation was not acknowledged, e.g. due to the addressed device not
     /// being available on the bus or the device not being ready to process requests
-    /// at the moment
+    /// at the moment.
     NoAcknowledge(NoAcknowledgeSource),
-    /// The peripheral receive buffer was overrun
+    /// The peripheral receive buffer was overrun.
     Overrun,
     /// A different error occurred. The original error may contain more information.
     Other,
 }
 
-/// I2C no acknowledge error source
+/// I2C no acknowledge error source.
 ///
 /// In cases where it is possible, a device should indicate if a no acknowledge
 /// response was received to an address versus a no acknowledge to a data byte.
@@ -216,12 +217,14 @@ pub enum NoAcknowledgeSource {
 }
 
 impl Error for ErrorKind {
+    #[inline]
     fn kind(&self) -> ErrorKind {
         *self
     }
 }
 
 impl core::fmt::Display for ErrorKind {
+    #[inline]
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             Self::Bus => write!(f, "Bus error occurred"),
@@ -237,6 +240,7 @@ impl core::fmt::Display for ErrorKind {
 }
 
 impl core::fmt::Display for NoAcknowledgeSource {
+    #[inline]
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             Self::Address => write!(f, "The device did not acknowledge its address"),
@@ -246,7 +250,7 @@ impl core::fmt::Display for NoAcknowledgeSource {
     }
 }
 
-/// I2C error type trait
+/// I2C error type trait.
 ///
 /// This just defines the error type, to be used by the other traits.
 pub trait ErrorType {
@@ -258,15 +262,15 @@ impl<T: ErrorType + ?Sized> ErrorType for &mut T {
     type Error = T::Error;
 }
 
-/// Address mode (7-bit / 10-bit)
+/// Address mode (7-bit / 10-bit).
 ///
 /// Note: This trait is sealed and should not be implemented outside of this crate.
 pub trait AddressMode: private::Sealed + 'static {}
 
-/// 7-bit address mode type
+/// 7-bit address mode type.
 pub type SevenBitAddress = u8;
 
-/// 10-bit address mode type
+/// 10-bit address mode type.
 pub type TenBitAddress = u16;
 
 impl AddressMode for SevenBitAddress {}
@@ -279,15 +283,15 @@ impl AddressMode for TenBitAddress {}
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt-03", derive(defmt::Format))]
 pub enum Operation<'a> {
-    /// Read data into the provided buffer
+    /// Read data into the provided buffer.
     Read(&'a mut [u8]),
-    /// Write data from the provided buffer
+    /// Write data from the provided buffer.
     Write(&'a [u8]),
 }
 
-/// Blocking I2C
+/// Blocking I2C.
 pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
-    /// Reads enough bytes from slave with `address` to fill `read`
+    /// Reads enough bytes from slave with `address` to fill `read`.
     ///
     /// # I2C Events (contract)
     ///
@@ -305,11 +309,12 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
+    #[inline]
     fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
         self.transaction(address, &mut [Operation::Read(read)])
     }
 
-    /// Writes bytes to slave with address `address`
+    /// Writes bytes to slave with address `address`.
     ///
     /// # I2C Events (contract)
     ///
@@ -325,12 +330,13 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `SAK` = slave acknowledge
     /// - `Bi` = ith byte of data
     /// - `SP` = stop condition
+    #[inline]
     fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
         self.transaction(address, &mut [Operation::Write(write)])
     }
 
     /// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
-    /// single transaction*
+    /// single transaction*.
     ///
     /// # I2C Events (contract)
     ///
@@ -351,6 +357,7 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
+    #[inline]
     fn write_read(&mut self, address: A, write: &[u8], read: &mut [u8]) -> Result<(), Self::Error> {
         self.transaction(
             address,
@@ -379,18 +386,22 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
 }
 
 impl<A: AddressMode, T: I2c<A> + ?Sized> I2c<A> for &mut T {
+    #[inline]
     fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
         T::read(self, address, read)
     }
 
+    #[inline]
     fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
         T::write(self, address, write)
     }
 
+    #[inline]
     fn write_read(&mut self, address: A, write: &[u8], read: &mut [u8]) -> Result<(), Self::Error> {
         T::write_read(self, address, write, read)
     }
 
+    #[inline]
     fn transaction(
         &mut self,
         address: A,