Merge #265

bors[bot] · robamu · web-flow · commit 9630d78417b2 · 2021-10-27T12:49:10.000Z
265: Cross-Reference Example files in documentation r=hargoniX a=robamu

I think these examples help would a lot, so I added them in the struct comment block

Co-authored-by: Robin Mueller &lt;robin.mueller.m@gmail.com&gt;
diff --git a/src/adc.rs b/src/adc.rs
@@ -2,6 +2,13 @@
 //!
 //! ADC1 and ADC2 share a reset line. To initialise both of them, use the
 //! [`adc12`](adc12) method.
+//!
+//! # Examples
+//!
+//! - [Reading a voltage using ADC1](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/adc.rs)
+//! - [Reading a temperature using ADC3](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/temperature.rs)
+//! - [Using ADC1 and ADC2 together](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/adc12.rs)
+//! - [Using ADC1 and ADC2 in parallel](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/adc12_parallel.rs)
 
 use crate::hal::adc::{Channel, OneShot};
 use crate::hal::blocking::delay::DelayUs;
diff --git a/src/crc.rs b/src/crc.rs
@@ -1,4 +1,8 @@
 //! Cyclic Redundancy Check (CRC)
+//!
+//! # Examples
+//!
+//! - [CRC example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/crc.rs)
 
 use core::convert::TryInto;
 use core::fmt;
diff --git a/src/dac.rs b/src/dac.rs
@@ -1,4 +1,8 @@
 //! Digital to Analog Converter (DAC)
+//!
+//! # Examples
+//!
+//! - [Simple DAC example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/dac.rs)
 
 use core::marker::PhantomData;
 use core::mem::MaybeUninit;
diff --git a/src/dma/mod.rs b/src/dma/mod.rs
@@ -73,6 +73,12 @@
 //! * [next_transfer_with](Transfer#method.next_transfer_with)
 //! * [next_dbm_transfer_with](Transfer#method.next_dbm_transfer_with)
 //!
+//! ## Examples
+//!
+//! - [Memory to Memory Transfer](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/dma.rs)
+//! - [Memory to Memory Transfer using Master DMA(MDMA)](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/mdma.rs)
+//! - [Using MDMA with multiple beats per burst](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/mdma_bursts.rs)
+//!
 //! ## Credits
 //!
 //! Adapted from
diff --git a/src/ethernet/mod.rs b/src/ethernet/mod.rs
@@ -5,6 +5,11 @@
 //! - SMSC LAN8742a
 //! - Micrel KSZ8081R
 //!
+//! # Examples
+//!
+//! - [Simple link checker for the Nucleo-H743ZI2](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/ethernet-nucleo-h743zi2.rs)
+//! - [Simple link checker for the STM32H747I-DISCO](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/ethernet-stm32h747i-disco.rs)
+//! - [Ethernet example for the STM32H747I-DISCO using RTIC](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/ethernet-rtic-stm32h747i-disco.rs)
 
 /// Station Management Interface (SMI) on an ethernet PHY
 pub trait StationManagement {
diff --git a/src/exti.rs b/src/exti.rs
@@ -1,4 +1,8 @@
 //! External interrupt controller
+//!
+//! # Examples
+//!
+//! - [External Interrupt via Button](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/exti_interrupt.rs)
 use crate::stm32::EXTI;
 
 /// EXTI trigger event
diff --git a/src/fmc.rs b/src/fmc.rs
@@ -25,6 +25,10 @@
 //!
 //! `sdram` usage is described
 //! [here](https://github.com/stm32-rs/stm32-fmc#usage).
+//!
+//! # Examples
+//!
+//! - [FMC example using the IS42S32800G SDRAM](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/fmc.rs)
 
 // From stm32_fmc
 use stm32_fmc::FmcPeripheral;
diff --git a/src/gpio.rs b/src/gpio.rs
@@ -1,4 +1,10 @@
 //! General Purpose Input / Output
+//!
+//! # Examples
+//!
+//! - [Simple Blinky](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/blinky.rs)
+//! - [Digital Read](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/digital_read.rs)
+//! - [External Interrupt via Button](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/exti_interrupt.rs)
 
 use core::marker::PhantomData;
 
diff --git a/src/i2c.rs b/src/i2c.rs
@@ -1,4 +1,9 @@
 //! Inter Integrated Circuit (I2C)
+//!
+//! # Examples
+//!
+//! - [I2C simple examples](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/i2c.rs)
+//! - [I2C example using I2C4 and BDMA](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/i2c4_bdma.rs)
 
 use core::cmp;
 use core::marker::PhantomData;
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,4 +1,4 @@
-//! *See the examples folder for more usage examples*
+//! *See the [examples](https://github.com/stm32-rs/stm32h7xx-hal/tree/master/examples) folder for more usage examples*
 //!
 //! This Hardware Abstraction Layer (HAL) provides the following functionality:
 //!
diff --git a/src/pwm.rs b/src/pwm.rs
@@ -6,6 +6,11 @@
 //!
 //! Timers support up to 4 simultaneous PWM output channels
 //!
+//! ## Examples
+//!
+//! - [Simple example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/pwm.rs)
+//! - [Advanced example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/pwm_advanced.rs)
+//!
 //! ## Usage
 //!
 //! ```rust
diff --git a/src/pwr.rs b/src/pwr.rs
@@ -10,6 +10,8 @@
 //!
 //! # Example
 //!
+//! You can also find a simple example [here](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/vos0.rs).
+//!
 //! ```rust
 //!     let dp = pac::Peripherals::take().unwrap();
 //!
diff --git a/src/qspi.rs b/src/qspi.rs
@@ -27,6 +27,11 @@
 //! qspi.write(0x00, &[0xAB, 0xCD]).unwrap();
 //! ```
 //!
+//! # Examples
+//!
+//! - [Simple QSPI example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/qspi.rs)
+//! - [QSPI using MDMA](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/qspi_mdma.rs)
+//!
 //! # Limitations
 //!
 //! This driver currently only supports indirect operation mode of the QSPI
diff --git a/src/rcc/mod.rs b/src/rcc/mod.rs
@@ -44,9 +44,13 @@
 //! specifying that clock. If this results in a configuration that cannot
 //! be achieved by hardware, `freeze` will panic.
 //!
-//! # Configuration Example
+//! # Examples
 //!
-//! A simple example:
+//! - [Simple RCC example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/rcc.rs).
+//! - [Fractional PLL configuration](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/fractional-pll.rs)
+//! - [MCO example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/mco.rs)
+//!
+//! Simple example:
 //!
 //! ```rust
 //!     let dp = pac::Peripherals::take().unwrap();
diff --git a/src/rng.rs b/src/rng.rs
@@ -1,4 +1,8 @@
 //! Random Number Generator
+//!
+//! # Examples
+//!
+//! - [Random Blinky](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/blinky_random.rs)
 
 use core::cmp;
 use core::mem;
diff --git a/src/rtc.rs b/src/rtc.rs
@@ -1,4 +1,8 @@
 //! Real-Time Clock
+//!
+//! # Examples
+//!
+//! - [RTC example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/rtc.rs)
 
 use cast::{f32, i32, u16, u32, u8};
 use chrono::prelude::*;
diff --git a/src/sai/mod.rs b/src/sai/mod.rs
@@ -1,4 +1,13 @@
-//! # Serial Audio Interface
+//! Serial Audio Interface
+//!
+//! # Examples
+//!
+//! - [Configure the SAI for PDM mode](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sai_pdm.rs)
+//!
+//! ## Examples using the Electro Smith Daisy Seed Board
+//!
+//! - [SAI with DMA](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sai_dma_passthru.rs)
+//! - [SAI with I2C](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sai-i2s-passthru.rs)
 
 use core::marker::PhantomData;
 
diff --git a/src/sdmmc.rs b/src/sdmmc.rs
@@ -4,6 +4,10 @@
 //!
 //! The H7 has two SDMMC peripherals, `SDMMC1` and `SDMMC2`.
 //!
+//! # Examples
+//!
+//! - [SDMMC example applicatio](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc.rs)
+//!
 //! ## IO Setup
 //!
 //! For high speed signalling (bus clock > 16MHz), the IO speed needs to be
diff --git a/src/serial.rs b/src/serial.rs
@@ -1,4 +1,9 @@
 //! Serial
+//!
+//! # Examples
+//!
+//! - [Simple Blocking Example](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/serial.rs)
+//! - [Serial Transfer using DMA](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/serial-dma.rs)
 
 use core::fmt;
 use core::marker::PhantomData;
diff --git a/src/spi.rs b/src/spi.rs
@@ -52,6 +52,11 @@
 //! - SPI4, SPI5: __APB__
 //! - SPI6: __PCLK4__
 //!
+//! # Examples
+//!
+//! - [Blocking SPI](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/spi.rs)
+//! - [SPI with DMA](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/spi-dma.rs).
+//!
 //! [embedded_hal]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/spi/index.html
 
 use crate::hal;
diff --git a/src/timer.rs b/src/timer.rs
@@ -1,4 +1,9 @@
 //! Timers
+//!
+//! # Examples
+//!
+//! - [Blinky using a Timer](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/blinky_timer.rs)
+//! - [64 bit microsecond timer](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/tick_timer.rs)
 
 // TODO: on the h7x3 at least, only TIM2, TIM3, TIM4, TIM5 can support 32 bits.
 // TIM1 is 16 bit.
diff --git a/src/usb_hs.rs b/src/usb_hs.rs
@@ -1,6 +1,11 @@
 //! USB OTG peripherals
 //!
 //! Requires the `usb_hs` feature.
+//!
+//! # Examples
+//!
+//! - [USB Serial Port](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/usb_serial.rs)
+//! - [USB Passthrough Examples](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/usb_passthrough.rs)
 
 use crate::rcc;
 use crate::stm32;
diff --git a/src/watchdog.rs b/src/watchdog.rs
@@ -1,4 +1,8 @@
 //! System Window Watchdog
+//!
+//! # Examples
+//!
+//! - [Example application](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/watchdog.rs)
 
 use crate::hal::watchdog::{Watchdog, WatchdogEnable};
 use crate::rcc::Ccdr;

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-//! See the examples folder for more usage examples`
	`1`	`+//! See the [examples](https://github.com/stm32-rs/stm32h7xx-hal/tree/master/examples) folder for more usage examples`
`2`	`2`	`//!`
`3`	`3`	`//! This Hardware Abstraction Layer (HAL) provides the following functionality:`
`4`	`4`	`//!`