Make a macro for the unsafe pin traits

 #![deny(missing_docs)]

Placate clippy

 #![deny(missing_docs)]

Author: Johannes Draaijer

src/lib.rs

@@ -2,6 +2,7 @@
 //!
 //! For initialisation, see [`new`], and [`new_with_mii`]
 #![no_std]
+#![deny(missing_docs)]
 
 /// Re-export
 #[cfg(feature = "stm32f7xx-hal")]

src/mac/miim.rs

@@ -10,8 +10,17 @@ use crate::{
 };
 
 /// MDIO pin types.
+///
+/// # Safety
+/// Only pins specified as ETH_MDIO in a part's reference manual
+/// may implement this trait
 pub unsafe trait MdioPin {}
+
 /// MDC pin types.
+///
+/// # Safety
+/// Only pins specified as ETH_MDC in a part's reference manual
+/// may implement this trait
 pub unsafe trait MdcPin {}
 
 #[inline(always)]
@@ -70,10 +79,12 @@ where
     Mdio: MdioPin,
     Mdc: MdcPin,
 {
+    /// Read MII register `reg` from the PHY at address `phy`
     pub fn read(&mut self, phy: u8, reg: u8) -> u16 {
         miim_read(&mut self.mac.eth_mac, phy, reg)
     }
 
+    /// Write the value `data` to MII register `reg` to the PHY at address `phy`
     pub fn write(&mut self, phy: u8, reg: u8, data: u16) {
         miim_write(&mut self.mac.eth_mac, phy, reg, data)
     }

src/mac/mod.rs

@@ -1,3 +1,5 @@
+//! Ethernet MAC driver implementation
+
 use core::ops::Deref;
 
 use crate::{
@@ -215,12 +217,14 @@ where
     MDIO: MdioPin,
     MDC: MdcPin,
 {
+    /// Read MII register `reg` from the PHY at address `phy`
     pub fn read(&mut self, phy: u8, reg: u8) -> u16 {
         self.eth_mac
             .mii(&mut self.mdio, &mut self.mdc)
             .read(phy, reg)
     }
 
+    /// Write the value `data` to MII register `reg` to the PHY at address `phy`
     pub fn write(&mut self, phy: u8, reg: u8, data: u16) {
         self.eth_mac
             .mii(&mut self.mdio, &mut self.mdc)

src/ring.rs

@@ -7,6 +7,7 @@ pub trait RingDescriptor {
     fn setup(&mut self, buffer: *const u8, len: usize, next: Option<&Self>);
 }
 
+/// An entry in a DMA Descriptor ring
 pub struct RingEntry<T: Clone + RingDescriptor> {
     desc: Aligned<A8, [T; 1]>,
     buffer: Aligned<A8, [u8; MTU]>,
@@ -31,6 +32,9 @@ impl<T: Clone + RingDescriptor + Default> Default for RingEntry<T> {
 }
 
 impl RingEntry<TxDescriptor> {
+    /// The initial value of a TxRingDescriptor
+    pub const INIT: Self = Self::new();
+
     /// Creates a RingEntry with a TxDescriptor.
     pub const fn new() -> Self {
         RingEntry {
@@ -41,6 +45,9 @@ impl RingEntry<TxDescriptor> {
 }
 
 impl RingEntry<RxDescriptor> {
+    /// The initial value of an RxRingDescriptor
+    pub const INIT: Self = Self::new();
+
     /// Creates a RingEntry with a RxDescriptor.
     pub const fn new() -> Self {
         RingEntry {

src/rx.rs

@@ -11,10 +11,14 @@ use crate::{
     ring::{RingDescriptor, RingEntry},
 };
 
+/// Errors that can occur during RX
 #[derive(Debug, PartialEq)]
 pub enum RxError {
+    /// Receiving would block
     WouldBlock,
+    /// The received packet was truncated
     Truncated,
+    /// An error occured with the DMA
     DmaError,
 }
 
@@ -39,6 +43,7 @@ const RXDESC_1_RER: u32 = 1 << 15;
 
 #[repr(C)]
 #[derive(Clone)]
+/// An RX DMA Descriptor
 pub struct RxDescriptor {
     desc: Descriptor,
 }
@@ -120,6 +125,7 @@ impl RxDescriptor {
     }
 }
 
+/// An RX DMA Ring Descriptor entry
 pub type RxRingEntry = RingEntry<RxDescriptor>;
 
 impl RingDescriptor for RxDescriptor {

src/setup.rs

@@ -1,3 +1,9 @@
+//! Pin definitions and setup functionality
+//!
+//! This module contains the unsafe traits that determine
+//! which pins can have a specific function, and provides
+//! functionality for setting up clocks and the MAC peripheral
+
 #[cfg(feature = "stm32f4xx-hal")]
 use stm32f4xx_hal::{
     bb,
@@ -142,33 +148,35 @@ pub(crate) fn setup() {
     });
 }
 
-/// RMII Reference Clock.
-pub unsafe trait RmiiRefClk {}
-
-/// RMII RX Data Valid.
-pub unsafe trait RmiiCrsDv {}
-
-/// RMII TX Enable.
-pub unsafe trait RmiiTxEN {}
-
-/// RMII TXD0.
-pub unsafe trait RmiiTxD0 {}
-
-/// RMII TXD1.
-pub unsafe trait RmiiTxD1 {}
-
-/// RMII RXD0.
-pub unsafe trait RmiiRxD0 {}
+macro_rules ! pin_trait {
+    ($([$name:ident, $doc:literal, $rm_name:literal]),*) => {
+        $(
+        #[doc = concat!($doc, "\n# Safety\nOnly pins specified as `ETH_RMII_", $rm_name, "` in a part's Reference Manual\nmay implement this trait.")]
+        pub unsafe trait $name {}
+        )*
+    }
+}
 
-/// RMII RXD1.
-pub unsafe trait RmiiRxD1 {}
+pin_trait!(
+    [RmiiRefClk, "RMII Reference Clock", "REF_CLK"],
+    [RmiiCrsDv, "RMII Rx Data Valid", "CRS_DV"],
+    [RmiiTxEN, "RMII TX Enable", "TX_EN"],
+    [RmiiTxD0, "RMII TX Data Pin 0", "TXD0"],
+    [RmiiTxD1, "RMII TX Data Pin 1", "TXD1"],
+    [RmiiRxD0, "RMII RX Data Pin 0", "RXD0"],
+    [RmiiRxD1, "RMII RX Data Pin 1", "RXD1"]
+);
 
 /// Trait needed to setup the pins for the Ethernet peripheral.
 pub trait AlternateVeryHighSpeed {
     /// Puts the pin in the Alternate Function 11 with Very High Speed.
     fn into_af11_very_high_speed(self);
 }
 
+/// A struct that represents a combination of pins to be used
+/// as RMII pins for the ethernet peripheral(s)
+// NOTE(missing_docs): all fields of this struct are self-explanatory
+#[allow(missing_docs)]
 pub struct EthPins<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1> {
     pub ref_clk: REFCLK,
     pub crs: CRS,

src/smoltcp_phy.rs

@@ -42,6 +42,8 @@ impl<'a, 'rx, 'tx, 'b> Device<'a> for &'b mut EthernetDMA<'rx, 'tx> {
     }
 }
 
+/// An Ethernet RX token that can be consumed in order to receive
+/// an ethernet packet.
 pub struct EthRxToken<'a> {
     packet: RxPacket<'a>,
 }

src/tx.rs

@@ -31,12 +31,14 @@ const TXDESC_0_ES: u32 = 1 << 15;
 const TXDESC_1_TBS_SHIFT: usize = 0;
 const TXDESC_1_TBS_MASK: u32 = 0x0fff << TXDESC_1_TBS_SHIFT;
 
+/// Errors that can occur during Ethernet TX
 #[derive(Debug, PartialEq)]
 pub enum TxError {
     /// Ring buffer is full
     WouldBlock,
 }
 
+/// A TX DMA Ring Descriptor
 #[repr(C)]
 #[derive(Clone)]
 pub struct TxDescriptor {
@@ -112,6 +114,7 @@ impl TxDescriptor {
     }
 }
 
+/// A TX DMA Ring Descriptor entry
 pub type TxRingEntry = RingEntry<TxDescriptor>;
 
 impl RingDescriptor for TxDescriptor {