Cleanup PARL_IO (#1508)

* Cleanup PARL_IO * remove not-needed `#[non_exhaustive]`
esp-rs · Apr 24, 2024 · 03b3245 · 03b3245
1 parent fa99a1a
commit 03b3245
Showing 1 changed file with 70 additions and 44 deletions.
diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs
@@ -76,6 +76,7 @@
 //! let mut transfer = parl_io_rx.read_dma(buffer).unwrap();
 //! transfer.wait().unwrap();
 //! ```
+#![warn(missing_docs)]
 
 use core::marker::PhantomData;
 
@@ -100,10 +101,16 @@ use crate::{
 #[allow(unused)]
 const MAX_DMA_SIZE: usize = 32736;
 
+/// Interrupts generated by the peripheral
 #[derive(EnumSetType)]
 pub enum ParlIoInterrupt {
+    /// Triggered when TX FIFO is empty. This interrupt indicates that there
+    /// might be error in the data sent by TX.
     TxFifoReEmpty,
+    /// Triggered when RX FIFO is full. This interrupt indicates that there
+    /// might be error in the data received by RX.
     RxFifoWOvf,
+    /// Triggered when TX finishes sending a complete frame of data.
     TxEof,
 }
 
@@ -313,6 +320,7 @@ impl<'d, P> ClkOutPin<'d, P>
 where
     P: OutputPin,
 {
+    /// Create a ClkOutPin
     pub fn new(pin: impl Peripheral<P = P> + 'd) -> Self {
         crate::into_ref!(pin);
         Self { pin }
@@ -340,6 +348,7 @@ impl<'d, P> ClkInPin<'d, P>
 where
     P: InputPin,
 {
+    /// Create a new ClkInPin
     pub fn new(pin: impl Peripheral<P = P> + 'd) -> Self {
         crate::into_ref!(pin);
         Self { pin }
@@ -372,6 +381,7 @@ impl<'d, P> RxClkInPin<'d, P>
 where
     P: InputPin,
 {
+    /// Create a new RxClkInPin
     pub fn new(pin: impl Peripheral<P = P> + 'd, sample_edge: SampleEdge) -> Self {
         crate::into_ref!(pin);
         Self { pin, sample_edge }
@@ -409,6 +419,7 @@ where
     P: NotContainsValidSignalPin + TxPins + ConfigurePins,
     VP: OutputPin,
 {
+    /// Create a [TxPinConfigWithValidPin]
     pub fn new(tx_pins: P, valid_pin: impl Peripheral<P = VP> + 'd) -> Self {
         crate::into_ref!(valid_pin);
         Self { tx_pins, valid_pin }
@@ -449,6 +460,7 @@ impl<P> TxPinConfigIncludingValidPin<P>
 where
     P: ContainsValidSignalPin + TxPins + ConfigurePins,
 {
+    /// Create a new [TxPinConfigIncludingValidPin]
     pub fn new(tx_pins: P) -> Self {
         Self { tx_pins }
     }
@@ -486,6 +498,7 @@ macro_rules! tx_pins {
             where
                 $($pin: OutputPin),+
             {
+                /// Create a new TX pin
                 #[allow(clippy::too_many_arguments)]
                 pub fn new(
                     $(
@@ -615,6 +628,7 @@ where
     P: NotContainsValidSignalPin + RxPins + ConfigurePins,
     VP: InputPin,
 {
+    /// Create a new [RxPinConfigWithValidPin]
     pub fn new(
         rx_pins: P,
         valid_pin: impl Peripheral<P = VP> + 'd,
@@ -678,6 +692,7 @@ impl<P> RxPinConfigIncludingValidPin<P>
 where
     P: ContainsValidSignalPin + RxPins + ConfigurePins,
 {
+    /// Create a new [RxPinConfigIncludingValidPin]
     pub fn new(rx_pins: P, enable_mode: EnableMode, eof_mode: EofMode) -> Self {
         Self {
             rx_pins,
@@ -730,6 +745,7 @@ macro_rules! rx_pins {
             where
                 $($pin: InputPin),+
             {
+                /// Create a new RX pin
                 #[allow(clippy::too_many_arguments)]
                 pub fn new(
                     $(
@@ -847,6 +863,7 @@ where
     CH: ChannelTypes,
     DM: Mode,
 {
+    /// Configure TX to use the given pins and settings
     pub fn with_config<P, CP>(
         self,
         mut tx_pins: P,
@@ -880,6 +897,7 @@ where
     CH: ChannelTypes,
     DM: Mode,
 {
+    /// Configure TX to use the given pins and settings
     pub fn with_config<P, CP>(
         self,
         mut tx_pins: P,
@@ -939,6 +957,7 @@ where
     CH: ChannelTypes,
     DM: Mode,
 {
+    /// Configure RX to use the given pins and settings
     pub fn with_config<P, CP>(
         self,
         mut rx_pins: P,
@@ -970,6 +989,7 @@ where
     CH: ChannelTypes,
     DM: Mode,
 {
+    /// Configure RX to use the given pins and settings
     pub fn with_config<P, CP>(
         self,
         mut rx_pins: P,
@@ -1115,6 +1135,7 @@ fn internal_clear_interrupts(interrupts: EnumSet<ParlIoInterrupt>) {
 /// Parallel IO in full duplex mode
 ///
 /// Full duplex mode might limit the maximum possible bit width.
+#[allow(missing_docs)]
 pub struct ParlIoFullDuplex<'d, CH, DM>
 where
     CH: ChannelTypes,
@@ -1131,6 +1152,7 @@ where
     CH::P: ParlIoPeripheral,
     DM: Mode,
 {
+    /// Create a new instance of [ParlIoFullDuplex]
     pub fn new(
         _parl_io: impl Peripheral<P = peripherals::PARL_IO> + 'd,
         mut dma_channel: Channel<'d, CH, DM>,
@@ -1187,6 +1209,7 @@ where
 }
 
 /// Parallel IO in half duplex / TX only mode
+#[allow(missing_docs)]
 pub struct ParlIoTxOnly<'d, CH, DM>
 where
     CH: ChannelTypes,
@@ -1202,6 +1225,7 @@ where
     CH::P: ParlIoPeripheral,
     DM: Mode,
 {
+    /// Create a new [ParlIoTxOnly]
     pub fn new(
         _parl_io: impl Peripheral<P = peripherals::PARL_IO> + 'd,
         mut dma_channel: Channel<'d, CH, DM>,
@@ -1254,6 +1278,7 @@ where
 }
 
 /// Parallel IO in half duplex / RX only mode
+#[allow(missing_docs)]
 pub struct ParlIoRxOnly<'d, CH, DM>
 where
     CH: ChannelTypes,
@@ -1269,6 +1294,7 @@ where
     CH::P: ParlIoPeripheral,
     DM: Mode,
 {
+    /// Create a new [ParlIoRxOnly] instance
     pub fn new(
         _parl_io: impl Peripheral<P = peripherals::PARL_IO> + 'd,
         mut dma_channel: Channel<'d, CH, DM>,
@@ -1378,8 +1404,7 @@ where
 {
     /// Perform a DMA write.
     ///
-    /// This will return a [DmaTransfer] owning the buffer(s) and the driver
-    /// instance.
+    /// This will return a [DmaTransfer]
     ///
     /// The maximum amount of data to be sent is 32736 bytes.
     pub fn write_dma<'t, TXBUF>(
@@ -1481,8 +1506,7 @@ where
 {
     /// Perform a DMA read.
     ///
-    /// This will return a [RxDmaTransfer] owning the buffer(s) and the driver
-    /// instance.
+    /// This will return a [RxDmaTransfer]
     ///
     /// The maximum amount of data is 32736 bytes when using [EofMode::ByteLen].
     ///
@@ -1585,6 +1609,47 @@ where
     }
 }
 
+/// Creates a TX channel
+pub struct TxCreator<'d, CH, DM>
+where
+    CH: ChannelTypes,
+    DM: Mode,
+{
+    tx_channel: CH::Tx<'d>,
+    phantom: PhantomData<DM>,
+}
+
+/// Creates a RX channel
+pub struct RxCreator<'d, CH, DM>
+where
+    CH: ChannelTypes,
+    DM: Mode,
+{
+    rx_channel: CH::Rx<'d>,
+    phantom: PhantomData<DM>,
+}
+
+/// Creates a TX channel
+pub struct TxCreatorFullDuplex<'d, CH, DM>
+where
+    CH: ChannelTypes,
+    DM: Mode,
+{
+    tx_channel: CH::Tx<'d>,
+    phantom: PhantomData<DM>,
+}
+
+/// Creates a RX channel
+pub struct RxCreatorFullDuplex<'d, CH, DM>
+where
+    CH: ChannelTypes,
+    DM: Mode,
+{
+    rx_channel: CH::Rx<'d>,
+    phantom: PhantomData<DM>,
+}
+
+#[doc(hidden)]
 #[cfg(feature = "async")]
 pub mod asynch {
     use core::task::Poll;
@@ -1606,7 +1671,7 @@ pub mod asynch {
 
     static TX_WAKER: AtomicWaker = AtomicWaker::new();
 
-    pub struct TxDoneFuture {}
+    struct TxDoneFuture {}
 
     impl TxDoneFuture {
         pub fn new() -> Self {
@@ -1708,10 +1773,7 @@ pub mod asynch {
 }
 
 mod private {
-    use core::marker::PhantomData;
-
     use super::{BitPackOrder, EofMode, Error, SampleEdge};
-    use crate::{dma::ChannelTypes, Mode};
 
     pub trait FullDuplex {}
 
@@ -1735,42 +1797,6 @@ mod private {
         fn configure(&mut self) -> Result<(), Error>;
     }
 
-    pub struct TxCreator<'d, CH, DM>
-    where
-        CH: ChannelTypes,
-        DM: Mode,
-    {
-        pub tx_channel: CH::Tx<'d>,
-        pub(crate) phantom: PhantomData<DM>,
-    }
-
-    pub struct RxCreator<'d, CH, DM>
-    where
-        CH: ChannelTypes,
-        DM: Mode,
-    {
-        pub rx_channel: CH::Rx<'d>,
-        pub(crate) phantom: PhantomData<DM>,
-    }
-
-    pub struct TxCreatorFullDuplex<'d, CH, DM>
-    where
-        CH: ChannelTypes,
-        DM: Mode,
-    {
-        pub tx_channel: CH::Tx<'d>,
-        pub(crate) phantom: PhantomData<DM>,
-    }
-
-    pub struct RxCreatorFullDuplex<'d, CH, DM>
-    where
-        CH: ChannelTypes,
-        DM: Mode,
-    {
-        pub rx_channel: CH::Rx<'d>,
-        pub(crate) phantom: PhantomData<DM>,
-    }
-
     #[cfg(esp32c6)]
     pub(super) enum WidSel {
         Bits16 = 0,