add docs

Author: burrbull

examples/gpio_erased.rs

@@ -23,7 +23,7 @@ fn main() -> ! {
     let mut gpioc = dp.GPIOC.split(&mut rcc.ahb);
     let mut gpiod = dp.GPIOD.split(&mut rcc.ahb);
 
-    let mut pin_array: [gpio::EPin<Input>; 4] = [
+    let mut pin_array: [gpio::ErasedPin<Input>; 4] = [
         gpiob
             .pb11
             .into_floating_input(&mut gpiob.moder, &mut gpiob.pupdr)

src/gpio.rs

@@ -78,8 +78,6 @@
 //! To make a pin dynamic, use the `into_dynamic` function, and then use the `make_<mode>` functions to
 //! change the mode
 
-#![allow(missing_docs)]
-
 use core::marker::PhantomData;
 
 use crate::pac::{Interrupt, EXTI};
@@ -89,9 +87,9 @@ use crate::Toggle;
 mod convert;
 use convert::PinMode;
 mod partially_erased;
-pub use partially_erased::{PEPin, PartiallyErasedPin};
+pub use partially_erased::PartiallyErasedPin;
 mod erased;
-pub use erased::{EPin, ErasedPin};
+pub use erased::ErasedPin;
 mod dynamic;
 pub use dynamic::{Dynamic, DynamicPin};
 mod hal_02;
@@ -114,11 +112,13 @@ pub trait GpioExt {
     fn split(self, ahb: &mut AHB) -> Self::Parts;
 }
 
+/// Id, port and mode for any pin
 pub trait PinExt {
+    /// Current pin mode
     type Mode;
-    /// Return pin number
+    /// Pin number
     fn pin_id(&self) -> u8;
-    /// Return port number
+    /// Port number starting from 0
     fn port_id(&self) -> u8;
 }
 
@@ -154,6 +154,7 @@ pub struct PushPull;
 /// Analog mode (type state)
 pub struct Analog;
 
+/// JTAG/SWD mote (type state)
 pub type Debugger = Alternate<0, PushPull>;
 
 mod sealed {
@@ -184,16 +185,23 @@ impl sealed::NotAlt for Analog {}
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Speed {
+    /// Low speed
     Low = 0,
+    /// Medium speed
     Medium = 1,
+    /// High speed
     High = 3,
 }
 
+/// GPIO interrupt trigger edge selection
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Edge {
+    /// Rising edge of voltage
     Rising,
+    /// Falling edge of voltage
     Falling,
+    /// Rising and falling edge of voltage
     RisingFalling,
 }
 
@@ -474,16 +482,16 @@ impl<const P: char, const N: u8, MODE> Pin<P, N, MODE> {
     ///
     /// This is useful when you want to collect the pins into an array where you
     /// need all the elements to have the same type
-    pub fn erase_number(self) -> PEPin<P, MODE> {
-        PEPin::new(N)
+    pub fn erase_number(self) -> PartiallyErasedPin<P, MODE> {
+        PartiallyErasedPin::new(N)
     }
 
     /// Erases the pin number and the port from the type
     ///
     /// This is useful when you want to collect the pins into an array where you
     /// need all the elements to have the same type
-    pub fn erase(self) -> EPin<MODE> {
-        EPin::new(P as u8 - b'A', N)
+    pub fn erase(self) -> ErasedPin<MODE> {
+        ErasedPin::new(P as u8 - b'A', N)
     }
 }
 
@@ -522,16 +530,19 @@ impl<const P: char, const N: u8, MODE> Pin<P, N, MODE> {
 }
 
 impl<const P: char, const N: u8, MODE> Pin<P, N, Output<MODE>> {
+    /// Drives the pin high
     #[inline(always)]
     pub fn set_high(&mut self) {
         self._set_high()
     }
 
+    /// Drives the pin low
     #[inline(always)]
     pub fn set_low(&mut self) {
         self._set_low()
     }
 
+    /// Is the pin in drive high or low mode?
     #[inline(always)]
     pub fn get_state(&self) -> PinState {
         if self.is_set_low() {
@@ -541,6 +552,7 @@ impl<const P: char, const N: u8, MODE> Pin<P, N, Output<MODE>> {
         }
     }
 
+    /// Drives the pin high or low depending on the provided value
     #[inline(always)]
     pub fn set_state(&mut self, state: PinState) {
         match state {
@@ -549,16 +561,19 @@ impl<const P: char, const N: u8, MODE> Pin<P, N, Output<MODE>> {
         }
     }
 
+    /// Is the pin in drive high mode?
     #[inline(always)]
     pub fn is_set_high(&self) -> bool {
         !self.is_set_low()
     }
 
+    /// Is the pin in drive low mode?
     #[inline(always)]
     pub fn is_set_low(&self) -> bool {
         self._is_set_low()
     }
 
+    /// Toggle pin output
     #[inline(always)]
     pub fn toggle(&mut self) {
         if self.is_set_low() {
@@ -573,11 +588,13 @@ impl<const P: char, const N: u8, MODE> Pin<P, N, MODE>
 where
     MODE: sealed::Readable,
 {
+    /// Is the input pin high?
     #[inline(always)]
     pub fn is_high(&self) -> bool {
         !self.is_low()
     }
 
+    /// Is the input pin low?
     #[inline(always)]
     pub fn is_low(&self) -> bool {
         self._is_low()
@@ -635,9 +652,14 @@ macro_rules! gpio {
                 }
             }
 
-            pub type $PXn<MODE> = super::PEPin<$port_id, MODE>;
+            #[doc="Common type for "]
+            #[doc=stringify!($GPIOX)]
+            #[doc=" related pins"]
+            pub type $PXn<MODE> = super::PartiallyErasedPin<$port_id, MODE>;
 
             $(
+                #[doc=stringify!($PXi)]
+                #[doc=" pin"]
                 pub type $PXi<MODE = Input> = super::Pin<$port_id, $i, MODE>;
 
                 $(
@@ -722,7 +744,6 @@ gpio!(GPIOF, gpiof, PF, 'F', PFn, [
     PF1: (pf1, 1, [4, 5]),
 ]);
 
-
 #[cfg(feature = "gpio-f303e")]
 gpio!(GPIOA, gpioa, PA, 'A', PAn, [
     PA0: (pa0, 0, [1, 3, 7, 8, 9, 10, 15]),
@@ -870,7 +891,6 @@ gpio!(GPIOH, gpioh, PH, 'H', PHn, [
     PH2: (ph2, 2, [1]),
 ]);
 
-
 #[cfg(feature = "gpio-f303")]
 gpio!(GPIOA, gpioa, PA, 'A', PAn, [
     PA0: (pa0, 0, [1, 3, 7, 8, 9, 10, 15]),
@@ -982,7 +1002,6 @@ gpio!(GPIOF, gpiof, PF, 'F', PFn, [
     PF10: (pf10, 10, [1, 3, 5]),
 ]);
 
-
 #[cfg(feature = "gpio-f333")]
 gpio!(GPIOA, gpioa, PA, 'A', PAn, [
     PA0: (pa0, 0, [1, 3, 7, 15]),
@@ -1054,7 +1073,6 @@ gpio!(GPIOF, gpiof, PF, 'F', PFn, [
     PF1: (pf1, 1, []),
 ]);
 
-
 #[cfg(feature = "gpio-f373")]
 gpio!(GPIOA, gpioa, PA, 'A', PAn, [
     PA0: (pa0, 0, [1, 2, 3, 7, 8, 11, 15]),

src/gpio/dynamic.rs

@@ -11,26 +11,36 @@ pub struct DynamicPin<const P: char, const N: u8> {
 
 /// Tracks the current pin state for dynamic pins
 pub enum Dynamic {
+    /// Floating input mode
     InputFloating,
+    /// Pull-up input mode
     InputPullUp,
+    /// Pull-down input mode
     InputPullDown,
+    /// Push-pull output mode
     OutputPushPull,
+    /// Open-drain output mode
     OutputOpenDrain,
 }
 
+/// Error for [DynamicPin]
 #[derive(Debug, PartialEq)]
 pub enum PinModeError {
+    /// For operations unsupported in current mode
     IncorrectMode,
 }
 
 impl Dynamic {
+    /// Is pin in readable mode
     pub fn is_input(&self) -> bool {
         use Dynamic::*;
         match self {
             InputFloating | InputPullUp | InputPullDown | OutputOpenDrain => true,
             OutputPushPull => false,
         }
     }
+
+    /// Is pin in writable mode
     pub fn is_output(&self) -> bool {
         use Dynamic::*;
         match self {
@@ -47,34 +57,39 @@ impl crate::Sealed for Unknown {}
 impl PinMode for Unknown {}
 
 impl<const P: char, const N: u8> DynamicPin<P, N> {
-    pub const fn new(mode: Dynamic) -> Self {
+    pub(super) const fn new(mode: Dynamic) -> Self {
         Self { mode }
     }
 
+    /// Switch pin into pull-up input
     #[inline]
     pub fn make_pull_up_input(&mut self, moder: &mut MODER<P>, pupdr: &mut PUPDR<P>) {
         // NOTE(unsafe), we have a mutable reference to the current pin
         Pin::<P, N, Unknown>::new().into_pull_up_input(moder, pupdr);
         self.mode = Dynamic::InputPullUp;
     }
+    /// Switch pin into pull-down input
     #[inline]
     pub fn make_pull_down_input(&mut self, moder: &mut MODER<P>, pupdr: &mut PUPDR<P>) {
         // NOTE(unsafe), we have a mutable reference to the current pin
         Pin::<P, N, Unknown>::new().into_pull_down_input(moder, pupdr);
         self.mode = Dynamic::InputPullDown;
     }
+    /// Switch pin into floating input
     #[inline]
     pub fn make_floating_input(&mut self, moder: &mut MODER<P>, pupdr: &mut PUPDR<P>) {
         // NOTE(unsafe), we have a mutable reference to the current pin
         Pin::<P, N, Unknown>::new().into_floating_input(moder, pupdr);
         self.mode = Dynamic::InputFloating;
     }
+    /// Switch pin into push-pull output
     #[inline]
     pub fn make_push_pull_output(&mut self, moder: &mut MODER<P>, otyper: &mut OTYPER<P>) {
         // NOTE(unsafe), we have a mutable reference to the current pin
         Pin::<P, N, Unknown>::new().into_push_pull_output(moder, otyper);
         self.mode = Dynamic::OutputPushPull;
     }
+    /// Switch pin into push-pull output with required voltage state
     #[inline]
     pub fn make_push_pull_output_in_state(
         &mut self,
@@ -86,12 +101,14 @@ impl<const P: char, const N: u8> DynamicPin<P, N> {
         Pin::<P, N, Unknown>::new().into_push_pull_output_in_state(moder, otyper, state);
         self.mode = Dynamic::OutputPushPull;
     }
+    /// Switch pin into open-drain output
     #[inline]
     pub fn make_open_drain_output(&mut self, moder: &mut MODER<P>, otyper: &mut OTYPER<P>) {
         // NOTE(unsafe), we have a mutable reference to the current pin
         Pin::<P, N, Unknown>::new().into_open_drain_output(moder, otyper);
         self.mode = Dynamic::OutputOpenDrain;
     }
+    /// Switch pin into open-drain output with required voltage state
     #[inline]
     pub fn make_open_drain_output_in_state(
         &mut self,
@@ -104,6 +121,7 @@ impl<const P: char, const N: u8> DynamicPin<P, N> {
         self.mode = Dynamic::OutputOpenDrain;
     }
 
+    /// Drives the pin high
     pub fn set_high(&mut self) -> Result<(), PinModeError> {
         if self.mode.is_output() {
             Pin::<P, N, Unknown>::new()._set_state(PinState::High);
@@ -112,6 +130,8 @@ impl<const P: char, const N: u8> DynamicPin<P, N> {
             Err(PinModeError::IncorrectMode)
         }
     }
+
+    /// Drives the pin low
     pub fn set_low(&mut self) -> Result<(), PinModeError> {
         if self.mode.is_output() {
             Pin::<P, N, Unknown>::new()._set_state(PinState::Low);
@@ -121,9 +141,12 @@ impl<const P: char, const N: u8> DynamicPin<P, N> {
         }
     }
 
+    /// Is the input pin high?
     pub fn is_high(&self) -> Result<bool, PinModeError> {
         self.is_low().map(|b| !b)
     }
+
+    /// Is the input pin low?
     pub fn is_low(&self) -> Result<bool, PinModeError> {
         if self.mode.is_input() {
             Ok(Pin::<P, N, Unknown>::new()._is_low())