Improve docs main page

src/lib.rs

@@ -7,9 +7,9 @@
 //!
 //! # Usage
 //!
-//! - Trying out the examples
+//! ## Trying out the examples
 //!
-//! ``` text
+//! ```bash
 //! $ git clone https://github.com/stm32-rs/stm32f1xx-hal
 //!
 //! # on another terminal
@@ -22,14 +22,86 @@
 //! $ cargo run --example hello
 //! ```
 //!
-//! - Building an application (binary crate)
+//! ## Building an application (binary crate)
 //!
-//! Follow the [cortex-m-quickstart] instructions and add this crate as a dependency
-//! and make sure you enable the "rt" Cargo feature of this crate.
+//! Follow the [cortex-m-quickstart] instructions, add this crate as a dependency
+//! and make sure you enable the "rt" Cargo feature of this crate. Also select which
+//! microcontroller you will be using by using the corresponding feature. The currently
+//! supported microcontrollers are:
+//!
+//! - stm32f103
+//! - stm32f100
+//!
+//! ```toml
+//! [dependencies.stm32f1xx-hal]
+//! version = "0.2.0"
+//! features = ["stm32f103", "rt"]
+//! ```
 //!
 //! [cortex-m-quickstart]: https://docs.rs/cortex-m-quickstart/~0.2.3
 //!
-//! # Examples
+//! ## Usage example
+//!
+//! The following example blinks an LED connected to PC13 which is where the LED is connected on the
+//! [blue_pill] board. If you are testing on a different breakout board, you may need
+//! to change the pin accordingly.
+//!
+//!
+//! ```rust
+//! #![deny(unsafe_code)]
+//! #![deny(warnings)]
+//! #![no_std]
+//! #![no_main]
+//! 
+//! extern crate panic_halt;
+//! 
+//! use nb::block;
+//! 
+//! use stm32f1xx_hal::{
+//!     prelude::*,
+//!     pac,
+//!     timer::Timer,
+//! };
+//! use cortex_m_rt::entry;
+//! 
+//! #[entry]
+//! fn main() -> ! {
+//!     // Get access to the core peripherals from the cortex-m crate
+//!     let cp = cortex_m::Peripherals::take().unwrap();
+//!     // Get access to the device specific peripherals from the peripheral access crate
+//!     let dp = pac::Peripherals::take().unwrap();
+//! 
+//!     // Take ownership over the raw flash and rcc devices and convert them into the corresponding
+//!     // HAL structs
+//!     let mut flash = dp.FLASH.constrain();
+//!     let mut rcc = dp.RCC.constrain();
+//! 
+//!     // Freeze the configuration of all the clocks in the system and store
+//!     // the frozen frequencies in `clocks`
+//!     let clocks = rcc.cfgr.freeze(&mut flash.acr);
+//! 
+//!     // Acquire the GPIOC peripheral
+//!     let mut gpioc = dp.GPIOC.split(&mut rcc.apb2);
+//! 
+//!     // Configure gpio C pin 13 as a push-pull output. The `crh` register is passed to the function
+//!     // in order to configure the port. For pins 0-7, crl should be passed instead.
+//!     let mut led = gpioc.pc13.into_push_pull_output(&mut gpioc.crh);
+//!     // Configure the syst timer to trigger an update every second
+//!     let mut timer = Timer::syst(cp.SYST, 1.hz(), clocks);
+//! 
+//!     // Wait for the timer to trigger an update and change the state of the LED
+//!     loop {
+//!         block!(timer.wait()).unwrap();
+//!         led.set_high();
+//!         block!(timer.wait()).unwrap();
+//!         led.set_low();
+//!     }
+//! }
+//! ```
+//!
+//! [blue_pill]: http://wiki.stm32duino.com/index.php?title=Blue_Pill
+//!
+//! # More examples
 //!
 //! See the [examples] folder.
 //!