Add missing docs

Leverage doc_comment macr

Author: Sh3Rm4n

Cargo.toml

@@ -32,6 +32,7 @@ nb = "0.1"
 paste = "1"
 rtcc = "0.2"
 stm32f3 = "0.12"
+doc-comment = "0.3.3"
 
 [dependencies.embedded-hal-can]
 version = "0.1.0"
@@ -73,7 +74,7 @@ gpio-f303e = []
 gpio-f333 = []
 gpio-f373 = []
 
-# Any Changes here should be mirrored in README.md, src/lib.rs, and
+# Any changes here should be mirrored in README.md, src/lib.rs, and
 # .github/workflows/ci.yml.
 stm32f301 = ["gpio-f302", "stm32f3/stm32f301", "device-selected"]
 stm32f318 = ["gpio-f302", "stm32f3/stm32f301", "device-selected"]

src/adc.rs

@@ -34,10 +34,11 @@ use crate::{
     pac::{ADC3, ADC3_4, ADC4},
 };
 
-/// ADC configuration
+/// Analog Digital Converter Peripheral
 // TODO: Remove `pub` from the register block once all functionalities are implemented.
 // Leave it here until then as it allows easy access to the registers.
 pub struct Adc<ADC> {
+    /// ADC Register
     pub rb: ADC,
     clocks: Clocks,
     ckmode: CkMode,
@@ -51,13 +52,21 @@ pub struct Adc<ADC> {
 /// E.g. For Sampletime T_19 the total conversion time (in ADC clock cycles) is
 /// 13 + 19 = 32 ADC Clock Cycles
 pub enum SampleTime {
+    /// 1.5 ADC clock cycles
     T_1,
+    /// 2.5 ADC clock cycles
     T_2,
+    /// 4.5 ADC clock cycles
     T_4,
+    /// 7.5 ADC clock cycles
     T_7,
+    /// 19.5 ADC clock cycles
     T_19,
+    /// 61.5 ADC clock cycles
     T_61,
+    /// 181.5 ADC clock cycles
     T_181,
+    /// 601.5 ADC clock cycles
     T_601,
 }
 
@@ -88,16 +97,21 @@ impl SampleTime {
 /// ADC operation mode
 // TODO: Implement other modes (DMA, Differential,…)
 pub enum OperationMode {
+    /// OneShot Mode
     OneShot,
 }
 
 #[derive(Clone, Copy, PartialEq)]
 /// ADC CkMode
 // TODO: Add ASYNCHRONOUS mode
 pub enum CkMode {
+    // /// Use Kernel Clock adc_ker_ck_input divided by PRESC. Asynchronous to AHB clock
     // ASYNCHRONOUS = 0,
+    /// Use AHB clock rcc_hclk3. In this case rcc_hclk must equal sys_d1cpre_ck
     SYNCDIV1 = 1,
+    /// Use AHB clock rcc_hclk3 divided by 2
     SYNCDIV2 = 2,
+    /// Use AHB clock rcc_hclk3 divided by 4
     SYNCDIV4 = 4,
 }
 

src/can.rs

@@ -43,22 +43,33 @@ pub struct CanFrame {
     pub data: Vec<u8, U8>,
 }
 
+/// Can Frame Filter Mode
+///
 /// Represents the operating mode of a CAN filter, which can either contain a
 /// list of identifiers, or a mask to match on.
 pub enum FilterMode {
+    /// Filter on a given Mask
     Mask,
+    /// Filter on a list of identifiers
     List,
 }
 
 /// A fully specified CAN filter with its associated list of of IDs or mask.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum CanFilterData {
+    /// Can Frame Identifier Filter
     IdFilter(CanId),
+    /// Filter for an identifier with a applied mask
     MaskFilter(u16, u16),
+    /// Filter for an extended identifier with a applied mask
     ExtendedMaskFilter(u32, u32),
+    /// Do not filter
     AcceptAll,
 }
 
+/// CAN Filter type
+///
+/// Used to specify the filter behavior
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct CanFilter {
     data: CanFilterData,
@@ -178,7 +189,9 @@ impl embedded_hal_can::Filter for CanFilter {
 }
 
 impl CanFilter {
-    /// Create a new filter with no assigned index. To actually active the filter call
+    /// Create a new filter with no assigned index.
+    ///
+    /// To actually active the filter call
     /// [`Receiver::set_filter`], which will assign an index.
     pub fn new(data: CanFilterData) -> CanFilter {
         CanFilter { data, index: None }
@@ -310,6 +323,7 @@ impl Can {
         (transmitter, fifo0, fifo1)
     }
 
+    /// Release owned peripherals
     pub fn free(self) -> (stm32::CAN, gpioa::PA11<AF9>, gpioa::PA12<AF9>) {
         (self.can, self._rx, self._tx)
     }

src/dma.rs

@@ -420,80 +420,86 @@ macro_rules! dma {
             ), )+
         },
     ) => {
-        pub mod $dmax {
-            use super::*;
-            use crate::pac::$DMAx;
+        doc_comment::doc_comment! {
+            concat!("All associated types, traits and methods of the ", stringify!($DMAx), " peripheral."),
+            pub mod $dmax {
+                use super::*;
+                use crate::pac::$DMAx;
 
-            impl DmaExt for $DMAx {
-                type Channels = Channels;
+                impl DmaExt for $DMAx {
+                    type Channels = Channels;
 
-                fn split(self, ahb: &mut AHB) -> Channels {
-                    ahb.enr().modify(|_, w| w.$dmaxen().set_bit());
+                    fn split(self, ahb: &mut AHB) -> Channels {
+                        ahb.enr().modify(|_, w| w.$dmaxen().set_bit());
 
-                    let mut channels = Channels {
-                        $( $chi: $Ci { _0: () }, )+
-                    };
+                        let mut channels = Channels {
+                            $( $chi: $Ci { _0: () }, )+
+                        };
 
-                    channels.reset();
-                    channels
+                        channels.reset();
+                        channels
+                    }
                 }
-            }
-
-            /// DMA channels
-            pub struct Channels {
-                $( pub $chi: $Ci, )+
-            }
 
-            impl Channels {
-                /// Reset the control registers of all channels.
-                /// This stops any ongoing transfers.
-                fn reset(&mut self) {
-                    $( self.$chi.reset(); )+
+                /// DMA channels
+                pub struct Channels {
+                    $(
+                        /// Channel
+                        pub $chi: $Ci,
+                    )+
                 }
-            }
 
-            $(
-                /// Singleton that represents a DMA channel
-                pub struct $Ci {
-                    _0: (),
+                impl Channels {
+                    /// Reset the control registers of all channels.
+                    /// This stops any ongoing transfers.
+                    fn reset(&mut self) {
+                        $( self.$chi.reset(); )+
+                    }
                 }
 
-                impl private::Channel for $Ci {
-                    fn ch(&self) -> &pac::dma1::CH {
-                        // NOTE(unsafe) $Ci grants exclusive access to this register
-                        unsafe { &(*$DMAx::ptr()).$chi }
+                $(
+                    /// Singleton that represents a DMA channel
+                    pub struct $Ci {
+                        _0: (),
                     }
-                }
 
-                impl Channel for $Ci {
-                    fn event_occurred(&self, event: Event) -> bool {
-                        use Event::*;
-
-                        // NOTE(unsafe) atomic read
-                        let flags = unsafe { (*$DMAx::ptr()).isr.read() };
-                        match event {
-                            HalfTransfer => flags.$htifi().bit_is_set(),
-                            TransferComplete => flags.$tcifi().bit_is_set(),
-                            TransferError => flags.$teifi().bit_is_set(),
-                            Any => flags.$gifi().bit_is_set(),
+                    impl private::Channel for $Ci {
+                        fn ch(&self) -> &pac::dma1::CH {
+                            // NOTE(unsafe) $Ci grants exclusive access to this register
+                            unsafe { &(*$DMAx::ptr()).$chi }
                         }
                     }
 
-                    fn clear_event(&mut self, event: Event) {
-                        use Event::*;
-
-                        // NOTE(unsafe) atomic write to a stateless register
-                        unsafe {
-                            &(*$DMAx::ptr()).ifcr.write(|w| match event {
-                                HalfTransfer => w.$chtifi().set_bit(),
-                                TransferComplete => w.$ctcifi().set_bit(),
-                                TransferError => w.$cteifi().set_bit(),
-                                Any => w.$cgifi().set_bit(),
-                            });
+                    impl Channel for $Ci {
+                        fn event_occurred(&self, event: Event) -> bool {
+                            use Event::*;
+
+                            // NOTE(unsafe) atomic read
+                            let flags = unsafe { (*$DMAx::ptr()).isr.read() };
+                            match event {
+                                HalfTransfer => flags.$htifi().bit_is_set(),
+                                TransferComplete => flags.$tcifi().bit_is_set(),
+                                TransferError => flags.$teifi().bit_is_set(),
+                                Any => flags.$gifi().bit_is_set(),
+                            }
+                        }
+
+                        fn clear_event(&mut self, event: Event) {
+                            use Event::*;
+
+                            // NOTE(unsafe) atomic write to a stateless register
+                            unsafe {
+                                &(*$DMAx::ptr()).ifcr.write(|w| match event {
+                                    HalfTransfer => w.$chtifi().set_bit(),
+                                    TransferComplete => w.$ctcifi().set_bit(),
+                                    TransferError => w.$cteifi().set_bit(),
+                                    Any => w.$cgifi().set_bit(),
+                                });
+                            }
                         }
                     }
-                }
-            )+
+                )+
+            }
         }
     };