[Book] Add macro reference section

[cakekindel]

As a user just starting to use the project (0.6.0-rc.4), let me start by saying I love the work you're doing! This project makes developing on embedded so modular and breezy, I am excited to contribute.

Now, the issue: the #[app] macro is too opaque. I feel right now in order to figure out the behavior of the rtic macros, users must look at rtic's source code and use cargo-expand.

This is far from an ideal UX and could be solved by maintaining a "macro reference" document (in the book or elsewhere) that would answer the following common questions ([n] refers to a comment in code sample below):

• [1]: what do #[init] and #[task] do to my functions?
• [2]: what is in the generated init module?
• [2]: what is the shape of init::Context?
• [3]: there's a field init::Context.core, what is the shape of that structure?
• [4]: what is in the generated foo module?
• [5]: what is the shape of foo::Context?
• [6]: what is available in the generated monotonics module?
• [6]: what other modules are available to me that aren't clearly documented?

Click to see code sample

use panic_semihosting as _;

#[rtic::app(/* <snip> */)]
mod app {
    use cortex_m_semihosting::{debug, hprintln};
    use systick_monotonic::*;

    #[monotonic(binds = SysTick, default = true)]
    type MyMono = Systick<100>;

    #[shared]
    struct Shared {}

    #[local]
    struct Local {}

    #[init] // [1]
    fn init(cx: init::Context /* [2] */) -> (Shared, Local, init::Monotonics) {
        let mono = Systick::new(cx.core.SYST, 12_000_000);
        //                         ~~~~ [3]
        foo::spawn_after(1.secs()).unwrap(); /*
        ~~~ [4] */

        (
            Shared {},
            Local {},
            init::Monotonics(mono),
        )
    }

    #[task]
    fn foo(_: foo::Context /* [5] */) {
        hprintln!("foo@{:?}", monotonics::now() /* [6] */).ok();
        foo::spawn_after(1.secs()).unwrap();
    }
}

[perlindgren]

We have discussed this, and it was intended for the under the hood section (its partly there but commented out).

On the one hand its valuable for a developer to understand what to expect from he macros, but on the hand this should not be necessary for using RTIC. Moreover, it would just reflect the current implementation and has no stability guarantees.

We aim to provide a separate design document, explaining the current implementation and soundness considerations. Intended to 1) make it easier to contribute to RTIC, 2) as a foundation for potential certification.

We will return to this after releasing 0.6.