Merge pull request #173 from Sh3Rm4n/doc-lint

Document every public item

Author: Sh3Rm4n

Cargo.toml

@@ -32,15 +32,12 @@ nb = "0.1"
 paste = "1"
 rtcc = "0.2"
 stm32f3 = "0.12"
+doc-comment = "0.3.3"
 
 [dependencies.embedded-hal-can]
 version = "0.1.0"
 optional = true
 
-[dependencies.heapless]
-version = "0.5.5"
-optional = true
-
 [dependencies.bare-metal]
 version = "0.2"
 features = ["const-fn"]
@@ -65,15 +62,15 @@ unproven = ["embedded-hal/unproven"]
 device-selected = []
 direct-call-deprecated = []
 rt = ["stm32f3/rt"]
-can = ["embedded-hal-can", "heapless"]
+can = ["embedded-hal-can"]
 
 gpio-f302 = []
 gpio-f303 = []
 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"]
@@ -138,3 +135,7 @@ required-features = ["stm32f303"]
 [[example]]
 name = "i2c_scanner"
 required-features = ["stm32f303xc"]
+
+[[example]]
+name = "gpio_erased"
+required-features = ["rt", "stm32f303xc"]

examples/can.rs

@@ -42,7 +42,7 @@ fn main() -> ! {
     let can_tx = gpioa.pa12.into_af9(&mut gpioa.moder, &mut gpioa.afrh);
 
     // Initialize the CAN peripheral
-    let can = Can::can(dp.CAN, can_rx, can_tx, &mut rcc.apb1);
+    let can = Can::new(dp.CAN, can_rx, can_tx, &mut rcc.apb1);
 
     // Uncomment the following line to enable CAN interrupts
     // can.listen(Event::Fifo0Fmp);
@@ -66,7 +66,7 @@ fn main() -> ! {
     asm::delay(100_000);
     let data: [u8; 1] = [0];
 
-    let frame = CanFrame::data_frame(CanId::BaseId(ID), &data);
+    let frame = CanFrame::new_data(CanId::BaseId(ID), &data);
 
     block!(can_tx.transmit(&frame)).expect("Cannot send first CAN frame");
 
@@ -81,7 +81,7 @@ fn main() -> ! {
             }
 
             let data: [u8; 1] = [counter];
-            let frame = CanFrame::data_frame(CanId::BaseId(ID), &data);
+            let frame = CanFrame::new_data(CanId::BaseId(ID), &data);
 
             block!(can_tx.transmit(&frame)).expect("Cannot send CAN frame");
         }

examples/gpio_erased.rs

@@ -0,0 +1,56 @@
+// TOOD Implement:
+// https://github.com/dfrankland/proton-c/commit/0289f1cfa15000d6b1b2a8175420c16ffdff7451
+#![no_main]
+#![no_std]
+
+use panic_semihosting as _;
+
+use cortex_m::asm;
+use cortex_m_rt::entry;
+use cortex_m_semihosting::hprintln;
+
+use hal::gpio::{self, Floating, Input};
+use hal::pac;
+use hal::prelude::*;
+use stm32f3xx_hal as hal;
+
+#[entry]
+fn main() -> ! {
+    let dp = pac::Peripherals::take().unwrap();
+
+    let mut rcc = dp.RCC.constrain();
+    let mut gpiob = dp.GPIOB.split(&mut rcc.ahb);
+    let mut gpioc = dp.GPIOC.split(&mut rcc.ahb);
+    let mut gpiod = dp.GPIOD.split(&mut rcc.ahb);
+
+    let mut pin_array: [gpio::PXx<Input<Floating>>; 4] = [
+        gpiob
+            .pb11
+            .into_floating_input(&mut gpiob.moder, &mut gpiob.pupdr)
+            .downgrade()
+            .downgrade(),
+        gpioc
+            .pc4
+            .into_floating_input(&mut gpioc.moder, &mut gpioc.pupdr)
+            .downgrade()
+            .downgrade(),
+        gpiod
+            .pd3
+            .into_floating_input(&mut gpiod.moder, &mut gpiod.pupdr)
+            .downgrade()
+            .downgrade(),
+        gpiod
+            .pd2
+            .into_floating_input(&mut gpiod.moder, &mut gpiod.pupdr)
+            .downgrade()
+            .downgrade(),
+    ];
+
+    hprintln!("Start scanning pin array").unwrap();
+    loop {
+        for pin in pin_array.iter_mut() {
+            hprintln!("Value is {}", pin.is_high().unwrap()).unwrap();
+            asm::delay(1_000);
+        }
+    }
+}

src/adc.rs

@@ -1,9 +1,14 @@
 //! API for the ADC (Analog to Digital Converter)
 //!
 //! # Examples
-//! Check `adc.rs` in the examples folder.
+//!
+//! Check out [examles/adc.rs].
+//!
 //! It can be built for the STM32F3Discovery running
 //! `cargo build --example adc --features=stm32f303xc`
+//!
+//! [examples/adc.rs]: https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.5.0/examples/adc.rs
+
 use crate::{
     gpio::Analog,
     rcc::{Clocks, AHB},
@@ -29,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,
@@ -46,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,
 }
 
@@ -83,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,
 }