Remove unnecessary prefixes/suffixes from Error and TxEvent enums (#2898)

* Remove unnecessary prefixes/suffixes from Error and TxEvent enums

* Remove #[allow(clippy::enum_variant_names ...)

* Use object+verb naming in Error enum variant

* Migration guide entry

* Remove ZeroLengthBufferPassed variant

* docs

esp-hal/MIGRATING-0.22.md

@@ -372,7 +372,7 @@ The `Config` struct's setters are now prefixed with `with_`. `parity_none`, `par
 
 The `DataBits`, `Parity`, and `StopBits` enum variants are no longer prefixed with the name of the enum.
 
-e.g.)
+e.g.
 
 ```diff
 - DataBits::DataBits8
@@ -387,6 +387,15 @@ The previous blocking implementation of `read_bytes` has been removed, and the n
 
 Any code which was previously using `read_bytes` to fill a buffer in a blocking manner will now need to implement the necessary logic to block until the buffer is filled in their application instead.
 
+The `Error` enum variant uses object+verb naming.
+
+e.g.
+
+```diff
+- RxGlichDetected
++ GlitchOccurred
+```
+
 ## Spi `with_miso` has been split
 
 Previously, `with_miso` set up the provided pin as an input and output, which was necessary for half duplex.

esp-hal/src/uart.rs

@@ -257,36 +257,29 @@ const CMD_CHAR_DEFAULT: u8 = 0x2b;
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub enum Error {
-    /// An invalid configuration argument was provided.
+    /// The RX FIFO overflow happened.
     ///
-    /// This error occurs when an incorrect or invalid argument is passed during
-    /// the configuration of the UART peripheral.
-    InvalidArgument,
-
-    /// The RX FIFO overflowed.
-    RxFifoOvf,
+    /// This error occurs when RX FIFO is full and a new byte is received.
+    FifoOverflowed,
 
     /// A glitch was detected on the RX line.
     ///
     /// This error occurs when an unexpected or erroneous signal (glitch) is
     /// detected on the UART RX line, which could lead to incorrect data
     /// reception.
-    RxGlitchDetected,
+    GlitchOccurred,
 
     /// A framing error was detected on the RX line.
     ///
     /// This error occurs when the received data does not conform to the
     /// expected UART frame format.
-    #[allow(clippy::enum_variant_names, reason = "Frame error is a common term")]
-    RxFrameError,
+    FrameFormatViolated,
 
     /// A parity error was detected on the RX line.
     ///
     /// This error occurs when the parity bit in the received data does not
     /// match the expected parity configuration.
-    /// with the `async` feature.
-    #[allow(clippy::enum_variant_names, reason = "Parity error is a common term")]
-    RxParityError,
+    ParityMismatch,
 }
 
 impl core::error::Error for Error {}
@@ -294,11 +287,10 @@ impl core::error::Error for Error {}
 impl core::fmt::Display for Error {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            Error::InvalidArgument => write!(f, "An invalid configuration argument was provided"),
-            Error::RxFifoOvf => write!(f, "The RX FIFO overflowed"),
-            Error::RxGlitchDetected => write!(f, "A glitch was detected on the RX line"),
-            Error::RxFrameError => write!(f, "A framing error was detected on the RX line"),
-            Error::RxParityError => write!(f, "A parity error was detected on the RX line"),
+            Error::FifoOverflowed => write!(f, "The RX FIFO overflowed"),
+            Error::GlitchOccurred => write!(f, "A glitch was detected on the RX line"),
+            Error::FrameFormatViolated => write!(f, "A framing error was detected on the RX line"),
+            Error::ParityMismatch => write!(f, "A parity error was detected on the RX line"),
         }
     }
 }
@@ -1527,8 +1519,8 @@ where
 
 #[derive(Debug, EnumSetType)]
 pub(crate) enum TxEvent {
-    TxDone,
-    TxFiFoEmpty,
+    Done,
+    FiFoEmpty,
 }
 
 #[derive(Debug, EnumSetType)]
@@ -1659,8 +1651,8 @@ impl UartTxFuture {
         let mut event_triggered = false;
         for event in self.events {
             event_triggered |= match event {
-                TxEvent::TxDone => interrupts_enabled.tx_done().bit_is_clear(),
-                TxEvent::TxFiFoEmpty => interrupts_enabled.txfifo_empty().bit_is_clear(),
+                TxEvent::Done => interrupts_enabled.tx_done().bit_is_clear(),
+                TxEvent::FiFoEmpty => interrupts_enabled.txfifo_empty().bit_is_clear(),
             }
         }
         event_triggered
@@ -1670,8 +1662,8 @@ impl UartTxFuture {
         self.uart.register_block().int_ena().modify(|_, w| {
             for event in self.events {
                 match event {
-                    TxEvent::TxDone => w.tx_done().bit(enable),
-                    TxEvent::TxFiFoEmpty => w.txfifo_empty().bit(enable),
+                    TxEvent::Done => w.tx_done().bit(enable),
+                    TxEvent::FiFoEmpty => w.txfifo_empty().bit(enable),
                 };
             }
             w
@@ -1759,7 +1751,7 @@ where
             }
 
             offset = next_offset;
-            UartTxFuture::new(self.uart.reborrow(), TxEvent::TxFiFoEmpty).await;
+            UartTxFuture::new(self.uart.reborrow(), TxEvent::FiFoEmpty).await;
         }
 
         Ok(count)
@@ -1773,7 +1765,7 @@ where
     pub async fn flush_async(&mut self) -> Result<(), Error> {
         let count = self.tx_fifo_count();
         if count > 0 {
-            UartTxFuture::new(self.uart.reborrow(), TxEvent::TxDone).await;
+            UartTxFuture::new(self.uart.reborrow(), TxEvent::Done).await;
         }
 
         Ok(())
@@ -1803,10 +1795,10 @@ where
     ///
     /// # Ok
     /// When successful, returns the number of bytes written to buf.
-    /// This method will never return Ok(0)
+    /// If the passed in buffer is of length 0, Ok(0) is returned.
     pub async fn read_async(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
         if buf.is_empty() {
-            return Err(Error::InvalidArgument);
+            return Ok(0);
         }
 
         loop {
@@ -1838,10 +1830,10 @@ where
             // check error events
             for event_happened in events_happened {
                 match event_happened {
-                    RxEvent::FifoOvf => return Err(Error::RxFifoOvf),
-                    RxEvent::GlitchDetected => return Err(Error::RxGlitchDetected),
-                    RxEvent::FrameError => return Err(Error::RxFrameError),
-                    RxEvent::ParityError => return Err(Error::RxParityError),
+                    RxEvent::FifoOvf => return Err(Error::FifoOverflowed),
+                    RxEvent::GlitchDetected => return Err(Error::GlitchOccurred),
+                    RxEvent::FrameError => return Err(Error::FrameFormatViolated),
+                    RxEvent::ParityError => return Err(Error::ParityMismatch),
                     RxEvent::FifoFull | RxEvent::CmdCharDetected | RxEvent::FifoTout => continue,
                 }
             }