improve rcc and gpio docs

Author: TheZoq2

src/gpio.rs

@@ -1,4 +1,26 @@
 //! General Purpose Input / Output
+//!
+//! To use the GPIO pins, you first need to configure the GPIO bank (GPIOA, GPIOB, ...) that you
+//! are interested in. This is done using the [GpioExt::split](trait.GpioExt.html#tymethod.split) function.
+//!
+//! ```
+//! let dp = pac::Peripherals::take().unwrap();
+//! let rcc = dp.RCC.constrain();
+//!
+//! let mut gpioa = dp.GPIOA.split(&mut rcc.ahb);
+//! ```
+//!
+//! The resulting [Parts](gpioa/struct.Parts.html) struct contains one field for each
+//! pin, as well as some shared register.
+//!
+//! To use a pin, first use the relevant `into_...` function in the [pin](gpioa/struct.PA0.html).
+//!
+//! ```rust
+//! let pa0 = gpioa.pa0.into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper);
+//! ```
+//!
+//! And finally, you can use the functions from the [InputPin](../prelude/trait._embedded_hal_digital_InputPin.html) or [OutputPin](../prelude/trait._embedded_hal_digital_OutputPin.html) traits in
+//! `embedded_hal`
 
 use core::convert::Infallible;
 use core::marker::PhantomData;

src/rcc.rs

@@ -32,6 +32,13 @@ impl RccExt for RCC {
 }
 
 /// Constrained RCC peripheral
+///
+/// An instance of this struct is aquired by calling the [constrain](trait.RccExt.html#tymethod.constrain) function on the [pac::RCC](../pac/struct.RCC.html) struct.
+///
+/// ```
+/// let dp = pac::Peripherals::take().unwrap();
+/// let rcc = dp.RCC.constrain();
+/// ```
 pub struct Rcc {
     /// AMBA High-performance Bus (AHB) registers
     pub ahb: AHB,
@@ -44,6 +51,14 @@ pub struct Rcc {
 }
 
 /// AMBA High-performance Bus (AHB) registers
+///
+/// An instance of this struct is aquired from the [Rcc](../struct.Rcc.html) struct.
+///
+/// ```
+/// let dp = pac::Peripherals::take().unwrap();
+/// let rcc = dp.RCC.constrain();
+/// use_ahb(&mut rcc.ahb)
+/// ```
 pub struct AHB {
     _0: (),
 }
@@ -61,6 +76,14 @@ impl AHB {
 }
 
 /// Advanced Peripheral Bus 1 (APB1) registers
+///
+/// An instance of this struct is aquired from the [Rcc](../struct.Rcc.html) struct.
+///
+/// ```
+/// let dp = pac::Peripherals::take().unwrap();
+/// let rcc = dp.RCC.constrain();
+/// use_ahb(&mut rcc.apb1)
+/// ```
 pub struct APB1 {
     _0: (),
 }
@@ -78,6 +101,14 @@ impl APB1 {
 }
 
 /// Advanced Peripheral Bus 2 (APB2) registers
+///
+/// An instance of this struct is aquired from the [Rcc](../struct.Rcc.html) struct.
+///
+/// ```
+/// let dp = pac::Peripherals::take().unwrap();
+/// let rcc = dp.RCC.constrain();
+/// use_ahb(&mut rcc.apb2)
+/// ```
 pub struct APB2 {
     _0: (),
 }
@@ -159,6 +190,14 @@ mod usb_clocking {
 }
 
 /// Clock configuration
+///
+/// An instance of this struct is aquired from the [Rcc](../struct.Rcc.html) struct.
+///
+/// ```
+/// let dp = pac::Peripherals::take().unwrap();
+/// let rcc = dp.RCC.constrain();
+/// use_ahb(&mut rcc.cfgr)
+/// ```
 pub struct CFGR {
     hse: Option<u32>,
     hclk: Option<u32>,