Merge pull request #233 from Sh3Rm4n/improve-doc

Improve doc

.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.

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][].

src/serial.rs

@@ -1,4 +1,11 @@
-//! Serial
+//! # Serial
+//!
+//! Asynchronous serial communication using the interal USART peripherals
+//!
+//! The serial modules implement the [`Read`] and [`Write`] traits.
+//!
+//! [`Read`]: embedded_hal::serial::Read
+//! [`Write`]: embedded_hal::serial::Write
 
 use core::{convert::Infallible, marker::PhantomData, ptr};
 

src/spi.rs

@@ -1,4 +1,6 @@
-//! Serial Peripheral Interface (SPI) bus
+//! # Serial Peripheral Interface (SPI) bus
+//!
+//! ## Examples
 //!
 //! A usage example of the can peripheral can be found at [examples/spi.rs]
 //!

src/syscfg.rs

@@ -1,4 +1,4 @@
-//! System configuration controller
+//! # System configuration controller
 
 use core::ops::Deref;
 

src/timer.rs

@@ -1,4 +1,10 @@
-//! Timers
+//! # Timers
+//!
+//! Abstractions of the internal timer peripherals
+//! The timer modules implements the [`CountDown`] and [`Periodic`] traits.
+//!
+//! [Read]: embedded_hal::timer::CountDown
+//! [Write]: embedded_hal::timer::Periodic
 
 use core::convert::{From, TryFrom};
 

src/usb.rs

@@ -1,4 +1,8 @@
-//! USB peripheral.
+//! # USB peripheral.
+//!
+//! Mostly builds upon the [`stm32_usbd`] crate.
+//!
+//! ## Examples
 //!
 //! See [examples/usb_serial.rs] for a usage example.
 //!

src/watchdog.rs

@@ -1,4 +1,6 @@
-//! Watchdog
+//! # Watchdog
+//!
+//! ## Examples
 //!
 //! A usage example of the watchdog can be found at [examples/can.rs]
 //!