From f90d5b2d0b648b22e323da7fb7fa401b8ede089b Mon Sep 17 00:00:00 2001
From: Dylan McKay <me@dylanmckay.io>
Date: Mon, 5 Nov 2018 22:40:04 +1300
Subject: [PATCH] Clean up the documentation and public exports

The interrupt helper struct does not need to be public.

Add some documentation to a bunch of types.
---
 core_generator/build.rs |  1 -
 src/interrupt.rs        | 35 +++++++++++++++++++++++++++++++++++
 src/legacy/mod.rs       |  3 ++-
 src/lib.rs              |  3 +++
 src/prelude.rs          | 26 ++------------------------
 5 files changed, 42 insertions(+), 26 deletions(-)
 create mode 100644 src/interrupt.rs

diff --git a/core_generator/build.rs b/core_generator/build.rs
index f6840ad..d9d94cd 100644
--- a/core_generator/build.rs
+++ b/core_generator/build.rs
@@ -66,7 +66,6 @@ fn generate_cores_mod_rs(mcus: &[Mcu]) -> Result<(), io::Error> {
     let path = cores_path().join("mod.rs");
     let mut w = File::create(&path)?;
 
-    writeln!(w, "//! Cores")?;
     writeln!(w)?;
     for mcu in mcus {
         let module_name = core_module_name(mcu);
diff --git a/src/interrupt.rs b/src/interrupt.rs
new file mode 100644
index 0000000..83d358b
--- /dev/null
+++ b/src/interrupt.rs
@@ -0,0 +1,35 @@
+//! Routines for managing interrupts.
+
+use core::prelude::v1::*;
+use core::marker::PhantomData;
+
+/// Helper struct that automatically restores interrupts
+/// on drop.
+struct DisableInterrupts(PhantomData<()>);
+
+/// Executes a closure, disabling interrupts until its completion.
+///
+/// Restores interrupts after the closure has completed
+/// execution.
+pub fn without_interrupts<F, T>(f: F) -> T
+    where F: FnOnce() -> T
+{
+    let _disabled = DisableInterrupts::new();
+    f()
+}
+
+impl DisableInterrupts {
+    #[inline]
+    pub fn new() -> DisableInterrupts {
+        unsafe { asm!("CLI") }
+        DisableInterrupts(PhantomData)
+    }
+}
+
+impl Drop for DisableInterrupts {
+    #[inline]
+    fn drop(&mut self) {
+        unsafe { asm!("SEI") }
+    }
+}
+
diff --git a/src/legacy/mod.rs b/src/legacy/mod.rs
index 7aaba83..1cd9e64 100644
--- a/src/legacy/mod.rs
+++ b/src/legacy/mod.rs
@@ -1,6 +1,7 @@
 //! Legacy code.
 //!
-//! The code in here needs to be cleaned up and rewritten.
+//! The code in here needs to be cleaned up and rewritten to use
+//! the new core-based API.
 //!
 //! Once a replacement exists, these legacy modules may be removed
 //! in a major release!
diff --git a/src/lib.rs b/src/lib.rs
index 7be2b49..1089a3b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -19,9 +19,12 @@ pub use self::pin::{DataDirection, Pin};
 
 pub mod prelude;
 pub mod legacy;
+/// Low level register-based API for device-specific operations.
 pub mod cores;
+pub mod interrupt;
 pub mod modules;
 
+/// Configuration for the currently-targeted microcontroller.
 pub mod config;
 
 mod register;
diff --git a/src/prelude.rs b/src/prelude.rs
index 8895d93..a5e529e 100644
--- a/src/prelude.rs
+++ b/src/prelude.rs
@@ -1,26 +1,4 @@
-use core::prelude::v1::*;
-use core::marker::PhantomData;
+//! Re-exports commonly-used APIs that can be imported at once.
 
-pub struct DisableInterrupts(PhantomData<()>);
+pub use interrupt::without_interrupts;
 
-impl DisableInterrupts {
-    #[inline]
-    pub fn new() -> DisableInterrupts {
-        unsafe { asm!("CLI") }
-        DisableInterrupts(PhantomData)
-    }
-}
-
-impl Drop for DisableInterrupts {
-    #[inline]
-    fn drop(&mut self) {
-        unsafe { asm!("SEI") }
-    }
-}
-
-pub fn without_interrupts<F, T>(f: F) -> T
-    where F: FnOnce() -> T
-{
-    let _disabled = DisableInterrupts::new();
-    f()
-}