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

@@ -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);

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") }
+    }
+}
+

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!

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;

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()
-}