Seal RccExt and FlashExt traits and improve documentation

Author: Sh3Rm4n

CHANGELOG.md

@@ -48,6 +48,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   0-clause as MIT conditions had to be met anyways. (🧂 IANAL). ([#309])
 - Renamed `Serial::raw_read` to `Serial::read_data_register`. ([#281])
 - Timer error type `AlreadyCancled` is no longer public constructable. ([#281])
+- Seal `FlashExt` and `RccExt` traits. These are no longer implementable by
+  a user of this crate. ([#281])
 - Move ADC from a macro to a generic implementation, meaning that
   it is possible to obtain an ADC instance via `Adc::new` instead of
   `Adc::adc1`. ([#281])

src/flash.rs

@@ -4,9 +4,17 @@
 
 use crate::pac::{flash, FLASH};
 
-/// Extension trait to constrain the FLASH peripheral
-pub trait FlashExt {
-    /// Constrains the FLASH peripheral to play nicely with the other abstractions
+impl crate::private::Sealed for FLASH {}
+
+/// Extension trait to constrain the [`FLASH`] peripheral
+pub trait FlashExt: crate::private::Sealed {
+    /// Constrains the [`FLASH`] peripheral.
+    ///
+    /// Consumes the [`pac::FLASH`] peripheral and converts it to a [`HAL`] internal type
+    /// constraining it's public access surface to fit the design of the [`HAL`].
+    ///
+    /// [`pac::FLASH`]: `crate::pac::FLASH`
+    /// [`HAL`]: `crate`
     fn constrain(self) -> Parts;
 }
 
@@ -31,7 +39,7 @@ pub struct ACR {
 
 impl ACR {
     pub(crate) fn acr(&mut self) -> &flash::ACR {
-        // NOTE(unsafe) this proxy grants exclusive access to this register
+        // SAFETY: This proxy grants exclusive access to this register
         unsafe { &(*FLASH::ptr()).acr }
     }
 }

src/lib.rs

@@ -4,9 +4,20 @@
  `stm32f3xx-hal` contains a multi device hardware abstraction on top of the
  peripheral access API for the STMicro [STM32F3][stm] series microcontrollers.
 
+ ## Philosophie
+
+ HAL (meaning **H**ardware **A**bstraction **L**ayer) is a generic term used in many contexts,
+ but in the specific context of this crate, it is meant to abstract away the control exposed
+ by the devices "[peripheral access crate](`crate::pac`)" to simplify initialization routines,
+ with a robust interface avoiding miss-configurations while still not abstracting to much away.
+
+ Also this crate's goal is to integrate well with the rest of the rust embedded ecosystem,
+ for example by implementing the [`embedded_hal`] traits or using crates, like [`embedded_time`],
+ or [`rtcc`].
+
  [stm]: https://www.st.com/en/microcontrollers-microprocessors/stm32f3-series.html
 
- ## Basic Usagee
+ ## Basic Usage
 
  ```rust
  #![no_std]

src/rcc.rs

@@ -66,9 +66,17 @@ use core::convert::TryInto;
 use crate::flash::ACR;
 use crate::time::rate::*;
 
-/// Extension trait that constrains the `RCC` peripheral
-pub trait RccExt {
-    /// Constrains the `RCC` peripheral so it plays nicely with the other abstractions
+impl crate::private::Sealed for RCC {}
+
+/// Extension trait that constrains the []`RCC`] peripheral
+pub trait RccExt: crate::private::Sealed {
+    /// Constrains the [`RCC`] peripheral.
+    ///
+    /// Consumes the [`pac::RCC`] peripheral and converts it to a [`HAL`] internal type
+    /// constraining it's public access surface to fit the design of the `HAL`.
+    ///
+    /// [`pac::RCC`]: `crate::pac::RCC`
+    /// [`HAL`]: `crate`
     fn constrain(self) -> Rcc;
 }
 
@@ -88,9 +96,8 @@ impl RccExt for RCC {
 
 /// Constrained RCC peripheral
 ///
-/// An instance of this struct is acquired by calling the
-/// [`constrain`](RccExt::constrain) function on the
-/// [`RCC`](crate::pac::RCC) struct.
+/// An instance of this struct is acquired by calling the [`constrain`](RccExt::constrain) function
+/// on the [`RCC`](crate::pac::RCC) struct.
 ///
 /// ```
 /// let dp = pac::Peripherals::take().unwrap();