Merge #193

193: Make `Peripherals` non-exhaustive and improve its docs r=therealprof a=jonas-schievink

This means that it's no longer a breaking change to add fields to it, which is important since Arm is likely to add more in upcoming architectures. They could also add extensions that add peripherals.

Co-authored-by: Jonas Schievink <jonasschievink@gmail.com>

1 files changed, 27 insertions, 35 deletions

diff --git a/src/peripheral/mod.rs b/src/peripheral/mod.rs
index 8854830..c84003f 100644
--- a/src/peripheral/mod.rs
+++ b/src/peripheral/mod.rs
@@ -1,5 +1,4 @@
-#![allow(clippy::needless_doctest_main)]
-//! Core peripherals
+//! Core peripherals.
 //!
 //! # API
 //!
@@ -9,41 +8,32 @@
 //! the [`Peripherals::take`](struct.Peripherals.html#method.take) method.
 //!
 //! ``` no_run
-//! use cortex_m::peripheral::Peripherals;
-//!
-//! fn main() {
-//!     let mut peripherals = Peripherals::take().unwrap();
-//!     peripherals.DWT.enable_cycle_counter();
-//! }
+//! # use cortex_m::peripheral::Peripherals;
+//! let mut peripherals = Peripherals::take().unwrap();
+//! peripherals.DWT.enable_cycle_counter();
 //! ```
 //!
 //! This method can only be successfully called *once* -- this is why the method returns an
 //! `Option`. Subsequent calls to the method will result in a `None` value being returned.
 //!
-//! ``` no_run
-//! use cortex_m::peripheral::Peripherals;
-//!
-//! fn main() {
-//!     let ok = Peripherals::take().unwrap();
-//!     let panics = Peripherals::take().unwrap();
-//! }
+//! ``` no_run, should_panic
+//! # use cortex_m::peripheral::Peripherals;
+//! let ok = Peripherals::take().unwrap();
+//! let panics = Peripherals::take().unwrap();
 //! ```
 //! A part of the peripheral API doesn't require access to a peripheral instance. This part of the
 //! API is provided as static methods on the peripheral types. One example is the
 //! [`DWT::get_cycle_count`](struct.DWT.html#method.get_cycle_count) method.
 //!
 //! ``` no_run
-//! use cortex_m::peripheral::{DWT, Peripherals};
-//!
-//! fn main() {
-//!     {
-//!         let mut peripherals = Peripherals::take().unwrap();
-//!         peripherals.DWT.enable_cycle_counter();
-//!     } // all the peripheral singletons are destroyed here
+//! # use cortex_m::peripheral::{DWT, Peripherals};
+//! {
+//!     let mut peripherals = Peripherals::take().unwrap();
+//!     peripherals.DWT.enable_cycle_counter();
+//! } // all the peripheral singletons are destroyed here
 //!
-//!     // but this method can be called without a DWT instance
-//!     let cyccnt = DWT::get_cycle_count();
-//! }
+//! // but this method can be called without a DWT instance
+//! let cyccnt = DWT::get_cycle_count();
 //! ```
 //!
 //! The singleton property can be *unsafely* bypassed using the `ptr` static method which is
@@ -51,17 +41,14 @@
 //! safe higher level abstractions.
 //!
 //! ``` no_run
-//! use cortex_m::peripheral::{DWT, Peripherals};
-//!
-//! fn main() {
-//!     {
-//!         let mut peripherals = Peripherals::take().unwrap();
-//!         peripherals.DWT.enable_cycle_counter();
-//!     } // all the peripheral singletons are destroyed here
+//! # use cortex_m::peripheral::{DWT, Peripherals};
+//! {
+//!     let mut peripherals = Peripherals::take().unwrap();
+//!     peripherals.DWT.enable_cycle_counter();
+//! } // all the peripheral singletons are destroyed here
 //!
-//!     // actually safe because this is an atomic read with no side effects
-//!     let cyccnt = unsafe { (*DWT::ptr()).cyccnt.read() };
-//! }
+//! // actually safe because this is an atomic read with no side effects
+//! let cyccnt = unsafe { (*DWT::ptr()).cyccnt.read() };
 //! ```
 //!
 //! # References
@@ -138,6 +125,10 @@ pub struct Peripherals {
 
     /// Trace Port Interface Unit (not present on Cortex-M0 variants)
     pub TPIU: TPIU,
+
+    // Private field making `Peripherals` non-exhaustive. We don't use `#[non_exhaustive]` so we
+    // can support older Rust versions.
+    _priv: (),
 }
 
 // NOTE `no_mangle` is used here to prevent linking different minor versions of this crate as that
@@ -200,6 +191,7 @@ impl Peripherals {
             TPIU: TPIU {
                 _marker: PhantomData,
             },
+            _priv: (),
         }
     }
 }