Improve top module documentation

Author: Sh3Rm4n

src/adc.rs

@@ -1,6 +1,6 @@
-//! Analog to Digital Converter.
+//! # Analog to Digital Converter.
 //!
-//! # Examples
+//! ## Examples
 //!
 //! Check out [examles/adc.rs][].
 //!

src/delay.rs

@@ -1,4 +1,9 @@
-//! Delays
+//! # Delays
+//!
+//! Implementations for the [`DelayMs`] and [`DelayUs`] traits
+//!
+//! [DelayMs]: embedded_hal::blocking::delay::DelayMs
+//! [DelayUs]: embedded_hal::blocking::delay::DelayUs
 
 use core::convert::From;
 

src/dma.rs

@@ -1,7 +1,9 @@
-//! Direct memory access (DMA) controller.
+//! # Direct memory access (DMA) controller.
 //!
 //! Currently DMA is only supported for STM32F303 or STM32F302 MCUs.
 //!
+//! ## Examples
+//!
 //! An example how to use DMA for serial, can be found at [examples/serial_dma.rs]
 //!
 //! [examples/serial_dma.rs]: https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.6.1/examples/serial_dma.rs

src/flash.rs

@@ -1,4 +1,6 @@
-//! Flash memory
+//! # Flash memory
+//!
+//! Abstractions of the internal flash module.
 
 use crate::pac::{flash, FLASH};
 

src/gpio.rs

@@ -1,4 +1,4 @@
-//! General Purpose Input / Output
+//! # General Purpose Input / Output
 //!
 //! To use the GPIO pins, you first need to configure the GPIO port (GPIOA, GPIOB, ...) that you
 //! are interested in. This is done using the [`GpioExt::split`] function.

src/i2c.rs

@@ -1,4 +1,6 @@
-//! Inter-Integrated Circuit (I2C) bus
+//! # Inter-Integrated Circuit (I2C) bus
+//!
+//! ## Examples
 //!
 //! A usage example of the i2c peripheral can be found at [examples/i2c_scanner.rs]
 //!

src/lib.rs

@@ -1,5 +1,5 @@
 /*!
- # stm32f3xx-hal
+ # `stm32f3xx-hal`
 
  `stm32f3xx-hal` contains a multi device hardware abstraction on top of the
  peripheral access API for the STMicro [STM32F3][stm] series microcontrollers.

src/prelude.rs

@@ -1,4 +1,12 @@
-//! Prelude
+//! # Prelude
+//!
+//! ```rust
+//! // Import common extension traits.
+//! //
+//! // This includes internal extension crates,
+//! // but also reexportet traits from embeded-hal or embedded time.
+//! use stm32f3xx-hal::prelude::*;
+//! ```
 
 #[cfg(any(feature = "stm32f302", feature = "stm32f303"))]
 pub use crate::dma::DmaExt as _stm32f3xx_hal_dma_DmaExt;

src/rcc.rs

@@ -1,4 +1,4 @@
-//! Reset and Clock Control
+//! # Reset and Clock Control
 //!
 //! The most important function this module
 //! delivers is the clock configuration.

src/rtc.rs

@@ -1,4 +1,4 @@
-//! Real Time Clock
+//! # Real Time Clock
 //!
 //! Interface to the real time clock. See STM32F303 reference manual, section 27.
 //! For more details, see [ST AN4759][].