Documented the prelude module

Author: jounathaen

src/prelude.rs

@@ -1,3 +1,41 @@
+//! Convenience re-export of multiple traits.
+//!
+//! This allows a HAL user to conveniently import this module and have all the
+//! helper traits already imported.
+//! Otherwise the use of peripherals would require the import of the
+//! corresponding module and the import of the trait, which connects this HAL
+//! to the autogenerated svd2rust API in [crate::stm32].
+//!
+//! # Example
+//!
+//! Consider the following code.
+//!
+//! ```
+//! #[entry]
+//! fn main() -> ! {
+//!     let dp = stm32::Peripherals::take().unwrap();
+//!     let gpiog = dp.GPIOG.split();
+//!     let mut led1 = gpiog.pg13.into_push_pull_output();
+//!     led1.set_high().unwrap();
+//! }
+//! ```
+//!
+//! Without the prelude we would have to import the following traits:
+//!
+//! ```
+//! use stm32f4xx_hal::gpio::GpioExt; // for the split method.
+//! use embedded_hal::digital::v2::OutputPin; // for the set_high() function.
+//! // And more use-statements with more complex code.
+//! ```
+//!
+//! These imports are a bit unintuitive, because we can create the objects
+//! without the import. But we need these traits to access most of their
+//! functions.
+//!
+//! The prelude module keeps the import section cleaner:
+//! ```
+//! use stm32f4xx_hal::prelude::*;
+//! ```
 pub use embedded_hal::digital::v2::InputPin as _embedded_hal_digital_v2_InputPin;
 pub use embedded_hal::digital::v2::OutputPin as _embedded_hal_digital_v2_OutputPin;
 pub use embedded_hal::digital::v2::StatefulOutputPin as _embedded_hal_digital_v2_StatefulOutputPin;