Begin adding some doc comments, update rustfmt config

esp-hal-common/src/delay.rs

@@ -1,3 +1,9 @@
+//! Delay driver
+//!
+//! Implement the `DelayMs` and `DelayUs` traits from [embedded-hal].
+//!
+//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
+
 use embedded_hal::blocking::delay::{DelayMs, DelayUs};
 
 pub use self::delay::Delay;
@@ -22,8 +28,6 @@ where
     }
 }
 
-// The delay implementation for RISC-V devices (ESP32-C3) uses the `SYSTIMER`
-// peripheral, as unfortunately this device does NOT implement the `mcycle` CSR.
 #[cfg(feature = "esp32c3")]
 mod delay {
     use crate::pac::SYSTIMER;
@@ -33,15 +37,23 @@ mod delay {
     // incremented by 1/16 μs on each `CNT_CLK` cycle.
     const CLK_FREQ_HZ: u64 = 16_000_000;
 
+    /// Delay driver
+    ///
+    /// Uses the `SYSTIMER` peripheral for counting clock cycles, as
+    /// unfortunately the ESP32-C3 does NOT implement the `mcycle` CSR, which is
+    /// how we would normally do this.
     pub struct Delay {
         systimer: SYSTIMER,
     }
 
     impl Delay {
+        /// Instantiate the `Delay` driver, taking ownership of the `SYSTIMER`
+        /// peripheral struct
         pub fn new(systimer: SYSTIMER) -> Self {
             Self { systimer }
         }
 
+        /// Delay for the specified number of microseconds
         pub fn delay(&self, us: u32) {
             let t0 = self.unit0_value();
             let clocks = (us as u64 * CLK_FREQ_HZ) / 1_000_000;
@@ -71,22 +83,25 @@ mod delay {
     }
 }
 
-// The delay implementation for Xtensa devices (ESP32, ESP32-S2, ESP32-S3) uses
-// the built-in timer from the `xtensa_lx` crate.
 #[cfg(not(feature = "esp32c3"))]
 mod delay {
     // FIXME: The ESP32-S2 and ESP32-S3 have fixed crystal frequencies of 40MHz.
     //        This will not always be the case when using the ESP32.
     const CLK_FREQ_HZ: u64 = 40_000_000;
 
+    /// Delay driver
+    ///
+    /// Uses the built-in Xtensa timer from the `xtensa_lx` crate.
     #[derive(Default)]
     pub struct Delay;
 
     impl Delay {
+        /// Instantiate the `Delay` driver
         pub fn new() -> Self {
             Self
         }
 
+        /// Delay for the specified number of microseconds
         pub fn delay(&self, us: u32) {
             let clocks = (us as u64 * CLK_FREQ_HZ) / 1_000_000;
             xtensa_lx::timer::delay(clocks as u32);

esp-hal-common/src/gpio.rs

@@ -1,3 +1,11 @@
+//! GPIO driver
+//!
+//! Defines a series of macros which allow for the definition of each chip's
+//! GPIO pins in a generic manner. Implements the various traits defined by
+//! [embedded-hal].
+//!
+//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
+
 pub use paste::paste;
 
 #[macro_export]

esp-hal-common/src/lib.rs

@@ -1,3 +1,21 @@
+//! `no_std` HAL implementations for the peripherals which are common among
+//! Espressif devices. Implements a number of the traits defined by
+//! [embedded-hal].
+//!
+//! This crate should not be used directly; you should use one of the
+//! device-specific HAL crates instead:
+//!
+//! - [esp32-hal]
+//! - [esp32c3-hal]
+//! - [esp32s2-hal]
+//! - [esp32s3-hal]
+//!
+//! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
+//! [esp32-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32-hal
+//! [esp32c3-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32c3-hal
+//! [esp32s2-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32s2-hal
+//! [esp32s3-hal]: https://github.com/jessebraham/esp-hal/tree/main/esp32s3-hal
+
 #![no_std]
 
 #[cfg(feature = "esp32")]

esp-hal-common/src/prelude.rs

@@ -1,3 +1,8 @@
+//! The prelude
+//!
+//! Re-exports all traits required for interacting with the various peripheral
+//! drivers implemented in this crate.
+
 pub use embedded_hal::{
     blocking::delay::{DelayMs as _, DelayUs as _},
     digital::v2::{

esp-hal-common/src/serial.rs

@@ -1,3 +1,5 @@
+//! UART driver
+
 use embedded_hal::serial::{Read, Write};
 
 #[cfg(any(feature = "esp32", feature = "esp32s3"))]
@@ -6,9 +8,11 @@ use crate::pac::{uart0::RegisterBlock, UART0, UART1};
 
 const UART_FIFO_SIZE: u16 = 128;
 
+/// Custom serial error type
 #[derive(Debug)]
 pub enum Error {}
 
+/// UART driver
 pub struct Serial<T> {
     uart: T,
 }
@@ -23,6 +27,7 @@ impl<T: Instance> Serial<T> {
     }
 }
 
+/// UART peripheral instance
 pub trait Instance {
     fn register_block(&self) -> &RegisterBlock;
 

esp-hal-common/src/timer.rs

@@ -1,3 +1,5 @@
+//! General-purpose timers
+
 use embedded_hal::{
     timer::{Cancel, CountDown, Periodic},
     watchdog::WatchdogDisable,
@@ -6,16 +8,19 @@ use void::Void;
 
 use crate::pac::{timg0::RegisterBlock, TIMG0, TIMG1};
 
+/// General-purpose timer
 pub struct Timer<T> {
     timg: T,
 }
 
+/// Custom timer error type
 pub enum Error {
     TimerActive,
     TimerInactive,
     AlarmInactive,
 }
 
+/// Timer driver
 impl<T> Timer<T>
 where
     T: Instance,
@@ -25,6 +30,7 @@ where
     }
 }
 
+/// Timer peripheral instance
 pub trait Instance {
     fn register_block(&self) -> &RegisterBlock;
 

rustfmt.toml

@@ -1,7 +1,12 @@
-edition = "2018"
-enum_discrim_align_threshold = 25
-group_imports = "StdExternalCrate"
+# Comments
+format_code_in_doc_comments = true
+normalize_comments          = true
+wrap_comments               = true
+
+# Enums
+enum_discrim_align_threshold = 35
+
+# Imports
+group_imports       = "StdExternalCrate"
 imports_granularity = "Crate"
-imports_layout = "HorizontalVertical"
-normalize_comments = true
-wrap_comments = true
+imports_layout      = "HorizontalVertical"