Fix doctests and run them in CI

Author: jonas-schievink

ci/script.sh

@@ -33,6 +33,8 @@ main() {
         data_overflow
     )
     if [ "$TARGET" != x86_64-unknown-linux-gnu ]; then
+        RUSTDOCFLAGS="-Cpanic=abort" cargo test --doc
+
         # linking with GNU LD
         for ex in "${examples[@]}"; do
             cargo rustc --target "$TARGET" --example "$ex" -- \

macros/Cargo.toml

@@ -20,6 +20,3 @@ proc-macro2 = "1.0"
 [dependencies.syn]
 features = ["extra-traits", "full"]
 version = "1.0"
-
-[dev-dependencies]
-cortex-m-rt = { path = "..", version = "0.6" }

macros/src/lib.rs

@@ -16,63 +16,6 @@ use syn::{
     ItemStatic, ReturnType, Stmt, Type, Visibility,
 };
 
-/// Attribute to declare the entry point of the program
-///
-/// **IMPORTANT**: This attribute must appear exactly *once* in the dependency graph. Also, if you
-/// are using Rust 1.30 the attribute must be used on a reachable item (i.e. there must be no
-/// private modules between the item and the root of the crate); if the item is in the root of the
-/// crate you'll be fine. This reachability restriction doesn't apply to Rust 1.31 and newer releases.
-///
-/// The specified function will be called by the reset handler *after* RAM has been initialized. In
-/// the case of the `thumbv7em-none-eabihf` target the FPU will also be enabled before the function
-/// is called.
-///
-/// The type of the specified function must be `[unsafe] fn() -> !` (never ending function)
-///
-/// # Properties
-///
-/// The entry point will be called by the reset handler. The program can't reference to the entry
-/// point, much less invoke it.
-///
-/// `static mut` variables declared within the entry point are safe to access. The compiler can't
-/// prove this is safe so the attribute will help by making a transformation to the source code: for
-/// this reason a variable like `static mut FOO: u32` will become `let FOO: &'static mut u32;`. Note
-/// that `&'static mut` references have move semantics.
-///
-/// # Examples
-///
-/// - Simple entry point
-///
-/// ``` no_run
-/// # #![no_main]
-/// # use cortex_m_rt_macros::entry;
-/// #[entry]
-/// fn main() -> ! {
-///     loop {
-///         /* .. */
-///     }
-/// }
-/// ```
-///
-/// - `static mut` variables local to the entry point are safe to modify.
-///
-/// ``` no_run
-/// # #![no_main]
-/// # use cortex_m_rt_macros::entry;
-/// #[entry]
-/// fn main() -> ! {
-///     static mut FOO: u32 = 0;
-///
-///     let foo: &'static mut u32 = FOO;
-///     assert_eq!(*foo, 0);
-///     *foo = 1;
-///     assert_eq!(*foo, 1);
-///
-///     loop {
-///         /* .. */
-///     }
-/// }
-/// ```
 #[proc_macro_attribute]
 pub fn entry(args: TokenStream, input: TokenStream) -> TokenStream {
     let mut f = parse_macro_input!(input as ItemFn);
@@ -172,118 +115,6 @@ pub fn entry(args: TokenStream, input: TokenStream) -> TokenStream {
     .into()
 }
 
-/// Attribute to declare an exception handler
-///
-/// **IMPORTANT**: If you are using Rust 1.30 this attribute must be used on reachable items (i.e.
-/// there must be no private modules between the item and the root of the crate); if the item is in
-/// the root of the crate you'll be fine. This reachability restriction doesn't apply to Rust 1.31
-/// and newer releases.
-///
-/// # Syntax
-///
-/// ```
-/// # use cortex_m_rt::exception;
-/// #[exception]
-/// fn SysTick() {
-///     // ..
-/// }
-///
-/// # fn main() {}
-/// ```
-///
-/// where the name of the function must be one of:
-///
-/// - `DefaultHandler`
-/// - `NonMaskableInt`
-/// - `HardFault`
-/// - `MemoryManagement` (a)
-/// - `BusFault` (a)
-/// - `UsageFault` (a)
-/// - `SecureFault` (b)
-/// - `SVCall`
-/// - `DebugMonitor` (a)
-/// - `PendSV`
-/// - `SysTick`
-///
-/// (a) Not available on Cortex-M0 variants (`thumbv6m-none-eabi`)
-///
-/// (b) Only available on ARMv8-M
-///
-/// # Usage
-///
-/// `#[exception] fn HardFault(..` sets the hard fault handler. The handler must have signature
-/// `[unsafe] fn(&ExceptionFrame) -> !`. This handler is not allowed to return as that can cause
-/// undefined behavior.
-///
-/// `#[exception] fn DefaultHandler(..` sets the *default* handler. All exceptions which have not
-/// been assigned a handler will be serviced by this handler. This handler must have signature
-/// `[unsafe] fn(irqn: i16) [-> !]`. `irqn` is the IRQ number (See CMSIS); `irqn` will be a negative
-/// number when the handler is servicing a core exception; `irqn` will be a positive number when the
-/// handler is servicing a device specific exception (interrupt).
-///
-/// `#[exception] fn Name(..` overrides the default handler for the exception with the given `Name`.
-/// These handlers must have signature `[unsafe] fn() [-> !]`. When overriding these other exception
-/// it's possible to add state to them by declaring `static mut` variables at the beginning of the
-/// body of the function. These variables will be safe to access from the function body.
-///
-/// # Properties
-///
-/// Exception handlers can only be called by the hardware. Other parts of the program can't refer to
-/// the exception handlers, much less invoke them as if they were functions.
-///
-/// `static mut` variables declared within an exception handler are safe to access and can be used
-/// to preserve state across invocations of the handler. The compiler can't prove this is safe so
-/// the attribute will help by making a transformation to the source code: for this reason a
-/// variable like `static mut FOO: u32` will become `let FOO: &mut u32;`.
-///
-/// # Examples
-///
-/// - Setting the `HardFault` handler
-///
-/// ```
-/// # extern crate cortex_m_rt;
-/// # extern crate cortex_m_rt_macros;
-/// # use cortex_m_rt_macros::exception;
-/// #[exception]
-/// fn HardFault(ef: &cortex_m_rt::ExceptionFrame) -> ! {
-///     // prints the exception frame as a panic message
-///     panic!("{:#?}", ef);
-/// }
-///
-/// # fn main() {}
-/// ```
-///
-/// - Setting the default handler
-///
-/// ```
-/// # use cortex_m_rt_macros::exception;
-/// #[exception]
-/// fn DefaultHandler(irqn: i16) {
-///     println!("IRQn = {}", irqn);
-/// }
-///
-/// # fn main() {}
-/// ```
-///
-/// - Overriding the `SysTick` handler
-///
-/// ```
-/// extern crate cortex_m_rt as rt;
-///
-/// use rt::exception;
-///
-/// #[exception]
-/// fn SysTick() {
-///     static mut COUNT: i32 = 0;
-///
-///     // `COUNT` is safe to access and has type `&mut i32`
-///     *COUNT += 1;
-///
-///     println!("{}", COUNT);
-/// }
-///
-/// # fn main() {}
-/// ```
 #[proc_macro_attribute]
 pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
     let mut f = parse_macro_input!(input as ItemFn);
@@ -521,74 +352,6 @@ pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
     }
 }
 
-/// Attribute to declare an interrupt (AKA device-specific exception) handler
-///
-/// **IMPORTANT**: If you are using Rust 1.30 this attribute must be used on reachable items (i.e.
-/// there must be no private modules between the item and the root of the crate); if the item is in
-/// the root of the crate you'll be fine. This reachability restriction doesn't apply to Rust 1.31
-/// and newer releases.
-///
-/// **NOTE**: This attribute is exposed by `cortex-m-rt` only when the `device` feature is enabled.
-/// However, that export is not meant to be used directly -- using it will result in a compilation
-/// error. You should instead use the device crate (usually generated using `svd2rust`) re-export of
-/// that attribute. You need to use the re-export to have the compiler check that the interrupt
-/// exists on the target device.
-///
-/// # Syntax
-///
-/// ``` ignore
-/// extern crate device;
-///
-/// // the attribute comes from the device crate not from cortex-m-rt
-/// use device::interrupt;
-///
-/// #[interrupt]
-/// fn USART1() {
-///     // ..
-/// }
-/// ```
-///
-/// where the name of the function must be one of the device interrupts.
-///
-/// # Usage
-///
-/// `#[interrupt] fn Name(..` overrides the default handler for the interrupt with the given `Name`.
-/// These handlers must have signature `[unsafe] fn() [-> !]`. It's possible to add state to these
-/// handlers by declaring `static mut` variables at the beginning of the body of the function. These
-/// variables will be safe to access from the function body.
-///
-/// If the interrupt handler has not been overridden it will be dispatched by the default exception
-/// handler (`DefaultHandler`).
-///
-/// # Properties
-///
-/// Interrupts handlers can only be called by the hardware. Other parts of the program can't refer
-/// to the interrupt handlers, much less invoke them as if they were functions.
-///
-/// `static mut` variables declared within an interrupt handler are safe to access and can be used
-/// to preserve state across invocations of the handler. The compiler can't prove this is safe so
-/// the attribute will help by making a transformation to the source code: for this reason a
-/// variable like `static mut FOO: u32` will become `let FOO: &mut u32;`.
-///
-/// # Examples
-///
-/// - Using state within an interrupt handler
-///
-/// ``` ignore
-/// extern crate device;
-///
-/// use device::interrupt;
-///
-/// #[interrupt]
-/// fn TIM2() {
-///     static mut COUNT: i32 = 0;
-///
-///     // `COUNT` is safe to access and has type `&mut i32`
-///     *COUNT += 1;
-///
-///     println!("{}", COUNT);
-/// }
-/// ```
 #[proc_macro_attribute]
 pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
     let mut f: ItemFn = syn::parse(input).expect("`#[interrupt]` must be applied to a function");
@@ -696,30 +459,6 @@ pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
     .into()
 }
 
-/// Attribute to mark which function will be called at the beginning of the reset handler.
-///
-/// **IMPORTANT**: This attribute can appear at most *once* in the dependency graph. Also, if you
-/// are using Rust 1.30 the attribute must be used on a reachable item (i.e. there must be no
-/// private modules between the item and the root of the crate); if the item is in the root of the
-/// crate you'll be fine. This reachability restriction doesn't apply to Rust 1.31 and newer
-/// releases.
-///
-/// The function must have the signature of `unsafe fn()`.
-///
-/// The function passed will be called before static variables are initialized. Any access of static
-/// variables will result in undefined behavior.
-///
-/// # Examples
-///
-/// ```
-/// # use cortex_m_rt_macros::pre_init;
-/// #[pre_init]
-/// unsafe fn before_main() {
-///     // do something here
-/// }
-///
-/// # fn main() {}
-/// ```
 #[proc_macro_attribute]
 pub fn pre_init(args: TokenStream, input: TokenStream) -> TokenStream {
     let f = parse_macro_input!(input as ItemFn);