improve rcc and gpio docs

src/gpio.rs

@@ -1,4 +1,32 @@
 //! 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 registers.
+//!
+//! 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] or [OutputPin] traits in
+//! `embedded_hal`
+//!
+//! For a complete example, see [examples/toggle.rs]
+//!
+//! [InputPin]: ../prelude/trait._embedded_hal_digital_InputPin.html
+//! [OutputPin]: ../prelude/trait._embedded_hal_digital_OutputPin.html
+//! [examples/toggle.rs]: https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.4.3/examples/toggle.rs
 
 use core::convert::Infallible;
 use core::marker::PhantomData;

src/rcc.rs

@@ -32,6 +32,15 @@ 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 +53,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 +78,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 +103,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 +192,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>,