add reachability check and docs to interrupt!

Author: japaric

src/generate/interrupt.rs

@@ -100,11 +100,33 @@ pub fn render(
                 ];
 
                 /// Macro to override a device specific interrupt handler
+                ///
+                /// # Syntax
+                ///
+                /// ``` ignore
+                /// interrupt!(
+                ///     // Name of the interrupt
+                ///     $Name:ident,
+                ///
+                ///     // Path to the interrupt handler (a function)
+                ///     $handler:path,
+                ///
+                ///     // Optional, state preserved across invocations of the handler
+                ///     state: $State:ty = $initial_state:expr,
+                /// );
+                /// ```
+                ///
+                /// Where `$Name` must match the name of one of the variants of the `Interrupt`
+                /// enum.
+                ///
+                /// The handler must have signature `fn()` is no state was associated to it;
+                /// otherwise its signature must be `fn(&mut $State)`.
                 #[cfg(feature = "rt")]
                 #[macro_export]
                 macro_rules! interrupt {
                     ($Name:ident, $handler:path,state: $State:ty = $initial_state:expr) => {
                         #[allow(unsafe_code)]
+                        #[deny(private_no_mangle_fns)] // raise an error if this item is not accessible
                         #[no_mangle]
                         pub unsafe extern "C" fn $Name() {
                             static mut STATE: $State = $initial_state;
@@ -121,6 +143,7 @@ pub fn render(
 
                     ($Name:ident, $handler:path) => {
                         #[allow(unsafe_code)]
+                        #[deny(private_no_mangle_fns)] // raise an error if this item is not accessible
                         #[no_mangle]
                         pub unsafe extern "C" fn $Name() {
                             // check that this interrupt exists