Discuss features in top level docs

Author: TheZoq2

src/lib.rs

@@ -17,11 +17,30 @@
 //! - stm32f103
 //! - stm32f100
 //!
-//! ```toml
-//! [dependencies.stm32f1xx-hal]
-//! version = "0.2.1"
-//! features = ["stm32f103", "rt"]
-//! ```
+//! ## Usage
+//!
+//! This crate supports multiple microcontrollers in the
+//! stm32f1 family. Which specific microcontroller you want to build for has to be
+//! specified with a feature, for example `stm32f103`.
+//!
+//! If no microcontroller is specified, the crate will not compile.
+//!
+//! The currently supported variants are
+//!
+//! - `stm32f100`
+//! - `stm32f101`
+//! - `stm32f103`
+//!
+//! You may also need to specify the density of the device with `medium`, `high` or `xl` 
+//! to enable certain peripherals. Generally the density can be determined by the 2nd character 
+//! after the number in the device name (i.e. For STM32F103C6U, the 6 indicates a low-density
+//! device) but check the datasheet or CubeMX to be sure.
+//! * 4, 6 => low density, no feature required
+//! * 8, B => `medium` feature
+//! * C, D, E => `high` feature
+//! * F, G => `xl` feature
+//!
+//! 
 //!
 //! [cortex-m-quickstart]: https://docs.rs/cortex-m-quickstart/0.3.1
 //!
@@ -36,7 +55,7 @@
 //! #![no_std]
 //! #![no_main]
 //! 
-//! extern crate panic_halt;
+//! use panic_halt as _;
 //! 
 //! use nb::block;
 //! 
@@ -46,6 +65,7 @@
 //!     timer::Timer,
 //! };
 //! use cortex_m_rt::entry;
+//! use embedded_hal::digital::v2::OutputPin;
 //! 
 //! #[entry]
 //! fn main() -> ! {
@@ -54,25 +74,23 @@
 //!     // 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
+//!     // 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`
+//!     // 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.
+//!     // 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, clocks)
-//!         .start_count_down(1.hz());
+//!     let mut timer = Timer::syst(cp.SYST, &clocks).start_count_down(1.hz());
 //! 
 //!     // Wait for the timer to trigger an update and change the state of the LED
 //!     loop {