Merge pull request stm32-rs#233 from Sh3Rm4n/improve-doc

Improve doc

Author: Sh3Rm4n

.github/workflows/ci.yml

@@ -115,6 +115,22 @@ jobs:
           command: check
           args: --features=ld,defmt,${{ matrix.mcu }} --test ${{ matrix.test }}
 
+  check-doc:
+    name: Check Documentation Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly
+          target: thumbv7em-none-eabihf
+          override: true
+          profile: minimal
+      - uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --features=stm32f303xc,rt,stm32-usbd,can
+
   clippy:
     name: Clippy
     runs-on: ubuntu-latest

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.
@@ -90,6 +90,7 @@
 #![allow(clippy::upper_case_acronyms)]
 #![warn(missing_docs)]
 #![deny(macro_use_extern_crate)]
+#![cfg_attr(nightly, deny(rustdoc::broken_intra_doc_links))]
 
 use cfg_if::cfg_if;
 

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.