From d351f55e1c8e60a9bbd69b40b84a39dab5d20051 Mon Sep 17 00:00:00 2001
From: Emil Fresk <emil.fresk@gmail.com>
Date: Thu, 25 Feb 2021 19:05:39 +0100
Subject: Documentation generation fixes

Test fixes
---
 macros/src/codegen.rs                  | 42 ++++++++++++----------------------
 macros/src/codegen/dispatchers.rs      | 24 +++++++++++--------
 macros/src/codegen/locals.rs           |  1 +
 macros/src/codegen/module.rs           | 28 +++++++++++++++++++----
 macros/src/codegen/post_init.rs        |  3 ++-
 macros/src/codegen/pre_init.rs         | 22 ++++++++++--------
 macros/src/codegen/resources.rs        |  3 ++-
 macros/src/codegen/resources_struct.rs |  3 ++-
 macros/src/codegen/software_tasks.rs   | 21 +++++++++--------
 macros/src/codegen/timer_queue.rs      | 24 +++++++++++--------
 macros/src/codegen/util.rs             |  9 ++------
 11 files changed, 99 insertions(+), 81 deletions(-)

(limited to 'macros/src')

diff --git a/macros/src/codegen.rs b/macros/src/codegen.rs
index 7885a4a9..c5d95687 100644
--- a/macros/src/codegen.rs
+++ b/macros/src/codegen.rs
@@ -57,6 +57,7 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
 
     let main = util::suffixed("main");
     mains.push(quote!(
+        #[doc(hidden)]
         mod rtic_ext {
             use super::*;
             #[no_mangle]
@@ -88,22 +89,6 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
     let user_code = &app.user_code;
     let name = &app.name;
     let device = &extra.device;
-
-    // Get the list of all tasks
-    // Currently unused, might be useful
-    let task_list = analysis.tasks.clone();
-
-    let mut tasks = vec![];
-
-    if !task_list.is_empty() {
-        tasks.push(quote!(
-            #[allow(non_camel_case_types)]
-            pub enum Tasks {
-                #(#task_list),*
-            }
-        ));
-    }
-
     let app_name = &app.name;
     let app_path = quote! {crate::#app_name};
 
@@ -114,25 +99,31 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
             let name = &monotonic.ident;
             let name_str = &name.to_string();
             let ty = &monotonic.ty;
-            let mangled_name = util::mangle_monotonic_type(&name_str);
             let ident = util::monotonic_ident(&name_str);
+            let ident = util::mark_internal_ident(&ident);
             let panic_str = &format!(
                 "Use of monotonic '{}' before it was passed to the runtime",
                 name_str
             );
+            let doc = &format!(
+                "This module holds the static implementation for `{}::now()`",
+                name_str
+            );
+            let user_imports = &app.user_imports;
 
             quote! {
                 pub use rtic::Monotonic as _;
 
-                #[doc(hidden)]
-                pub type #mangled_name = #ty;
-
-                /// This module holds the static implementation for `#name::now()`
+                #[doc = #doc]
                 #[allow(non_snake_case)]
                 pub mod #name {
-                    /// Access the global `Monotonic` implementation, not that this will panic
-                    /// before the this `Monotonic` has been passed to the RTIC runtime.
-                    pub fn now() -> rtic::time::Instant<#app_path::#mangled_name> {
+                    #(
+                        #[allow(unused_imports)]
+                        #user_imports
+                    )*
+
+                    /// Read the current time from this monotonic
+                    pub fn now() -> rtic::time::Instant<#ty> {
                         rtic::export::interrupt::free(|_| {
                             use rtic::Monotonic as _;
                             use rtic::time::Clock as _;
@@ -182,9 +173,6 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
 
             #(#root_software_tasks)*
 
-            /// Unused
-            #(#tasks)*
-
             /// app module
             #(#mod_app)*
 
diff --git a/macros/src/codegen/dispatchers.rs b/macros/src/codegen/dispatchers.rs
index d3adee0d..dc33b1af 100644
--- a/macros/src/codegen/dispatchers.rs
+++ b/macros/src/codegen/dispatchers.rs
@@ -26,15 +26,16 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
             })
             .collect::<Vec<_>>();
 
-        let doc = format!(
-            "Software tasks to be dispatched at priority level {}",
-            level,
-        );
+        // let doc = format!(
+        //     "Software tasks to be dispatched at priority level {}",
+        //     level,
+        // );
         let t = util::spawn_t_ident(level);
         items.push(quote!(
             #[allow(non_camel_case_types)]
             #[derive(Clone, Copy)]
-            #[doc = #doc]
+            // #[doc = #doc]
+            #[doc(hidden)]
             pub enum #t {
                 #(#variants,)*
             }
@@ -42,6 +43,7 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
 
         let n = util::capacity_typenum(channel.capacity, true);
         let rq = util::rq_ident(level);
+        let rq = util::mark_internal_ident(&rq);
         let (rq_ty, rq_expr) = {
             (
                 quote!(rtic::export::SCRQ<#t, #n>),
@@ -51,12 +53,12 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
             )
         };
 
-        let doc = format!(
-            "Queue of tasks ready to be dispatched at priority level {}",
-            level
-        );
+        // let doc = format!(
+        //     "Queue of tasks ready to be dispatched at priority level {}",
+        //     level
+        // );
         items.push(quote!(
-            #[doc = #doc]
+            #[doc(hidden)]
             static mut #rq: #rq_ty = #rq_expr;
         ));
 
@@ -67,7 +69,9 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
                 let task = &app.software_tasks[name];
                 let cfgs = &task.cfgs;
                 let fq = util::fq_ident(name);
+                let fq = util::mark_internal_ident(&fq);
                 let inputs = util::inputs_ident(name);
+                let inputs = util::mark_internal_ident(&inputs);
                 let (_, tupled, pats, _) = util::regroup_inputs(&task.inputs);
 
                 let locals_new = if task.locals.is_empty() {
diff --git a/macros/src/codegen/locals.rs b/macros/src/codegen/locals.rs
index 336c0b21..5725a151 100644
--- a/macros/src/codegen/locals.rs
+++ b/macros/src/codegen/locals.rs
@@ -49,6 +49,7 @@ pub fn codegen(
         ));
         items.push(quote!(
             #(#cfgs)*
+            #[doc(hidden)]
             static mut #name: #ty = #expr
         ));
         values.push(quote!(
diff --git a/macros/src/codegen/module.rs b/macros/src/codegen/module.rs
index 25260bea..41f5b22a 100644
--- a/macros/src/codegen/module.rs
+++ b/macros/src/codegen/module.rs
@@ -68,6 +68,7 @@ pub fn codegen(
 
     if ctxt.has_resources(app) {
         let ident = util::resources_ident(ctxt, app);
+        let ident = util::mark_internal_ident(&ident);
         let lt = if resources_tick {
             lt = Some(quote!('a));
             Some(quote!('a))
@@ -122,8 +123,8 @@ pub fn codegen(
             .monotonics
             .iter()
             .map(|(_, monotonic)| {
-                let mono = util::mangle_monotonic_type(&monotonic.ident.to_string());
-                quote! {#app_path::#mono}
+                let mono = &monotonic.ty;
+                quote! {#mono}
             })
             .collect();
 
@@ -185,8 +186,11 @@ pub fn codegen(
         let args = &args;
         let tupled = &tupled;
         let fq = util::fq_ident(name);
+        let fq = util::mark_internal_ident(&fq);
         let rq = util::rq_ident(priority);
+        let rq = util::mark_internal_ident(&rq);
         let inputs = util::inputs_ident(name);
+        let inputs = util::mark_internal_ident(&inputs);
 
         let device = &extra.device;
         let enum_ = util::interrupt_ident();
@@ -199,6 +203,7 @@ pub fn codegen(
         // Spawn caller
         items.push(quote!(
         #(#cfgs)*
+        /// Spawns the task directly
         pub fn spawn(#(#args,)*) -> Result<(), #ty> {
             let input = #tupled;
 
@@ -226,13 +231,16 @@ pub fn codegen(
         // Schedule caller
         for (_, monotonic) in &app.monotonics {
             let instants = util::monotonic_instants_ident(name, &monotonic.ident);
+            let instants = util::mark_internal_ident(&instants);
             let monotonic_name = monotonic.ident.to_string();
 
             let tq = util::tq_ident(&monotonic.ident.to_string());
+            let tq = util::mark_internal_ident(&tq);
             let t = util::schedule_t_ident();
             let m = &monotonic.ident;
-            let m_mangled = util::mangle_monotonic_type(&monotonic_name);
+            let mono_type = &monotonic.ty;
             let m_ident = util::monotonic_ident(&monotonic_name);
+            let m_ident = util::mark_internal_ident(&m_ident);
             let m_isr = &monotonic.args.binds;
             let enum_ = util::interrupt_ident();
 
@@ -255,15 +263,24 @@ pub fn codegen(
                 )
             };
 
+            let user_imports = &app.user_imports;
+
             items.push(quote!(
+            /// Holds methods related to this monotonic
             pub mod #m {
+                #(
+                    #[allow(unused_imports)]
+                    #user_imports
+                )*
+
                 #(#cfgs)*
+                /// Spawns the task after a set duration relative to the current time
                 pub fn spawn_after<D>(
                     duration: D
                     #(,#args)*
                 ) -> Result<(), #ty>
                     where D: rtic::time::duration::Duration + rtic::time::fixed_point::FixedPoint,
-                        D::T: Into<<#app_path::#m_mangled as rtic::time::Clock>::T>,
+                        D::T: Into<<#app_path::#mono_type as rtic::time::Clock>::T>,
                 {
 
                     let instant = if rtic::export::interrupt::free(|_| unsafe { #app_path::#m_ident.is_none() }) {
@@ -276,8 +293,9 @@ pub fn codegen(
                 }
 
                 #(#cfgs)*
+                /// Spawns the task at a fixed time instant
                 pub fn spawn_at(
-                    instant: rtic::time::Instant<#app_path::#m_mangled>
+                    instant: rtic::time::Instant<#app_path::#mono_type>
                     #(,#args)*
                 ) -> Result<(), #ty> {
                     unsafe {
diff --git a/macros/src/codegen/post_init.rs b/macros/src/codegen/post_init.rs
index 8ebcb12b..96c5df80 100644
--- a/macros/src/codegen/post_init.rs
+++ b/macros/src/codegen/post_init.rs
@@ -13,7 +13,7 @@ pub fn codegen(app: &App, analysis: &Analysis) -> Vec<TokenStream2> {
     if !analysis.late_resources.is_empty() {
         // BTreeSet wrapped in a vector
         for name in analysis.late_resources.first().unwrap() {
-            let mangled_name = util::mangle_ident(&name);
+            let mangled_name = util::mark_internal_ident(&name);
             // If it's live
             let cfgs = app.late_resources[name].cfgs.clone();
             if analysis.locations.get(name).is_some() {
@@ -35,6 +35,7 @@ pub fn codegen(app: &App, analysis: &Analysis) -> Vec<TokenStream2> {
 
         // Store the monotonic
         let name = util::monotonic_ident(&monotonic.to_string());
+        let name = util::mark_internal_ident(&name);
         stmts.push(quote!(#name = Some(monotonics.#idx);));
     }
 
diff --git a/macros/src/codegen/pre_init.rs b/macros/src/codegen/pre_init.rs
index fbfff3b5..d5105445 100644
--- a/macros/src/codegen/pre_init.rs
+++ b/macros/src/codegen/pre_init.rs
@@ -17,6 +17,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
     for (name, task) in &app.software_tasks {
         let cap = task.args.capacity;
         let fq_ident = util::fq_ident(name);
+        let fq_ident = util::mark_internal_ident(&fq_ident);
 
         stmts.push(quote!(
             (0..#cap).for_each(|i| #fq_ident.enqueue_unchecked(i));
@@ -77,19 +78,20 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
     }
 
     // Initialize monotonic's interrupts
-    for (ident, priority, name) in app
-        .monotonics
-        .iter()
-        .map(|(ident, monotonic)| (ident, &monotonic.args.priority, &monotonic.args.binds))
+    for (_, monotonic) in app.monotonics.iter()
+    //.map(|(ident, monotonic)| (ident, &monotonic.args.priority, &monotonic.args.binds))
     {
+        let priority = &monotonic.args.priority;
+        let binds = &monotonic.args.binds;
+
         // Compile time assert that this priority is supported by the device
         stmts.push(quote!(let _ = [(); ((1 << #nvic_prio_bits) - #priority as usize)];));
 
         let app_name = &app.name;
         let app_path = quote! {crate::#app_name};
-        let mono_type = util::mangle_monotonic_type(&ident.to_string());
+        let mono_type = &monotonic.ty;
 
-        if &*name.to_string() == "SysTick" {
+        if &*binds.to_string() == "SysTick" {
             stmts.push(quote!(
                 core.SCB.set_priority(
                     rtic::export::SystemHandler::SysTick,
@@ -97,7 +99,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
                 );
 
                 // Always enable monotonic interrupts if they should never be off
-                if !#app_path::#mono_type::DISABLE_INTERRUPT_ON_EMPTY_QUEUE {
+                if !<#mono_type as rtic::Monotonic>::DISABLE_INTERRUPT_ON_EMPTY_QUEUE {
                     core::mem::transmute::<_, cortex_m::peripheral::SYST>(())
                         .enable_interrupt();
                 }
@@ -107,13 +109,13 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
             let interrupt = util::interrupt_ident();
             stmts.push(quote!(
                 core.NVIC.set_priority(
-                    #rt_err::#interrupt::#name,
+                    #rt_err::#interrupt::#binds,
                     rtic::export::logical2hw(#priority, #nvic_prio_bits),
                 );
 
                 // Always enable monotonic interrupts if they should never be off
-                if !#app_path::#mono_type::DISABLE_INTERRUPT_ON_EMPTY_QUEUE {
-                    rtic::export::NVIC::unmask(#app_path::#rt_err::#interrupt::#name);
+                if !<#mono_type as rtic::Monotonic>::DISABLE_INTERRUPT_ON_EMPTY_QUEUE {
+                    rtic::export::NVIC::unmask(#app_path::#rt_err::#interrupt::#binds);
                 }
             ));
         }
diff --git a/macros/src/codegen/resources.rs b/macros/src/codegen/resources.rs
index 76871e59..fa52b86d 100644
--- a/macros/src/codegen/resources.rs
+++ b/macros/src/codegen/resources.rs
@@ -21,7 +21,7 @@ pub fn codegen(
     for (name, res, expr, _) in app.resources(analysis) {
         let cfgs = &res.cfgs;
         let ty = &res.ty;
-        let mangled_name = util::mangle_ident(&name);
+        let mangled_name = util::mark_internal_ident(&name);
 
         {
             let section = if expr.is_none() {
@@ -42,6 +42,7 @@ pub fn codegen(
             let attrs = &res.attrs;
             mod_app.push(quote!(
                 #[allow(non_upper_case_globals)]
+                #[doc(hidden)]
                 #(#attrs)*
                 #(#cfgs)*
                 #section
diff --git a/macros/src/codegen/resources_struct.rs b/macros/src/codegen/resources_struct.rs
index bffe9431..8ed8a291 100644
--- a/macros/src/codegen/resources_struct.rs
+++ b/macros/src/codegen/resources_struct.rs
@@ -31,7 +31,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
             None
         };
         let ty = &res.ty;
-        let mangled_name = util::mangle_ident(&name);
+        let mangled_name = util::mark_internal_ident(&name);
 
         // let ownership = &analysis.ownerships[name];
         let r_prop = &res.properties;
@@ -112,6 +112,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
 
     let doc = format!("Resources `{}` has access to", ctxt.ident(app));
     let ident = util::resources_ident(ctxt, app);
+    let ident = util::mark_internal_ident(&ident);
     let item = quote!(
         #[allow(non_snake_case)]
         #[doc = #doc]
diff --git a/macros/src/codegen/software_tasks.rs b/macros/src/codegen/software_tasks.rs
index a760b067..a39fe4cc 100644
--- a/macros/src/codegen/software_tasks.rs
+++ b/macros/src/codegen/software_tasks.rs
@@ -37,6 +37,7 @@ pub fn codegen(
 
         // Create free queues and inputs / instants buffers
         let fq = util::fq_ident(name);
+        let fq = util::mark_internal_ident(&fq);
 
         let (fq_ty, fq_expr, mk_uninit): (_, _, Box<dyn Fn() -> Option<_>>) = {
             (
@@ -48,8 +49,9 @@ pub fn codegen(
             )
         };
         mod_app.push(quote!(
-            /// Queue version of a free-list that keeps track of empty slots in
-            /// the following buffers
+            // /// Queue version of a free-list that keeps track of empty slots in
+            // /// the following buffers
+            #[doc(hidden)]
             static mut #fq: #fq_ty = #fq_expr;
         ));
 
@@ -57,28 +59,29 @@ pub fn codegen(
             .map(|_| quote!(core::mem::MaybeUninit::uninit()))
             .collect::<Vec<_>>();
 
-        let app_name = &app.name;
-        let app_path = quote! {crate::#app_name};
-
         for (_, monotonic) in &app.monotonics {
             let instants = util::monotonic_instants_ident(name, &monotonic.ident);
-            let m = util::mangle_monotonic_type(&monotonic.ident.to_string());
+            let instants = util::mark_internal_ident(&instants);
+            let mono_type = &monotonic.ty;
 
             let uninit = mk_uninit();
             mod_app.push(quote!(
                 #uninit
-                /// Buffer that holds the instants associated to the inputs of a task
+                // /// Buffer that holds the instants associated to the inputs of a task
+                #[doc(hidden)]
                 static mut #instants:
-                    [core::mem::MaybeUninit<rtic::time::Instant<#app_path::#m>>; #cap_lit] =
+                    [core::mem::MaybeUninit<rtic::time::Instant<#mono_type>>; #cap_lit] =
                     [#(#elems,)*];
             ));
         }
 
         let uninit = mk_uninit();
         let inputs_ident = util::inputs_ident(name);
+        let inputs_ident = util::mark_internal_ident(&inputs_ident);
         mod_app.push(quote!(
             #uninit
-            /// Buffer that holds the inputs of a task
+            // /// Buffer that holds the inputs of a task
+            #[doc(hidden)]
             static mut #inputs_ident: [core::mem::MaybeUninit<#input_ty>; #cap_lit] =
                 [#(#elems,)*];
         ));
diff --git a/macros/src/codegen/timer_queue.rs b/macros/src/codegen/timer_queue.rs
index ea2fee66..82d0ac98 100644
--- a/macros/src/codegen/timer_queue.rs
+++ b/macros/src/codegen/timer_queue.rs
@@ -26,9 +26,10 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
                 })
                 .collect::<Vec<_>>();
 
-            let doc = "Tasks that can be scheduled".to_string();
+            // let doc = "Tasks that can be scheduled".to_string();
             items.push(quote!(
-                #[doc = #doc]
+                // #[doc = #doc]
+                #[doc(hidden)]
                 #[allow(non_camel_case_types)]
                 #[derive(Clone, Copy)]
                 enum #t {
@@ -41,25 +42,27 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
     for (_, monotonic) in &app.monotonics {
         let monotonic_name = monotonic.ident.to_string();
         let tq = util::tq_ident(&monotonic_name);
+        let tq = util::mark_internal_ident(&tq);
         let t = util::schedule_t_ident();
-        let m = util::mangle_monotonic_type(&monotonic_name);
+        let mono_type = &monotonic.ty;
         let m_ident = util::monotonic_ident(&monotonic_name);
+        let m_ident = util::mark_internal_ident(&m_ident);
         let app_name = &app.name;
         let app_path = quote! {crate::#app_name};
 
         // Static variables and resource proxy
         {
-            let doc = &format!("Timer queue for {}", monotonic_name);
+            // let doc = &format!("Timer queue for {}", monotonic_name);
             let cap = app
                 .software_tasks
                 .iter()
                 .map(|(_name, task)| task.args.capacity)
                 .sum();
             let n = util::capacity_typenum(cap, false);
-            let tq_ty = quote!(rtic::export::TimerQueue<#m, #t, #n>);
+            let tq_ty = quote!(rtic::export::TimerQueue<#mono_type, #t, #n>);
 
             items.push(quote!(
-                #[doc = #doc]
+                #[doc(hidden)]
                 static mut #tq: #tq_ty = rtic::export::TimerQueue(
                     rtic::export::BinaryHeap(
                         rtic::export::iBinaryHeap::new()
@@ -68,12 +71,12 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
             ));
 
             let mono = util::monotonic_ident(&monotonic_name);
-            let doc = &format!("Storage for {}", monotonic_name);
-            let mono_ty = quote!(Option<#m>);
+            let mono = util::mark_internal_ident(&mono);
+            // let doc = &format!("Storage for {}", monotonic_name);
 
             items.push(quote!(
-                #[doc = #doc]
-                static mut #mono: #mono_ty = None;
+                #[doc(hidden)]
+                static mut #mono: Option<#mono_type> = None;
             ));
         }
 
@@ -89,6 +92,7 @@ pub fn codegen(app: &App, analysis: &Analysis, _extra: &Extra) -> Vec<TokenStrea
                     let cfgs = &task.cfgs;
                     let priority = task.args.priority;
                     let rq = util::rq_ident(priority);
+                    let rq = util::mark_internal_ident(&rq);
                     let rqt = util::spawn_t_ident(priority);
 
                     // The interrupt that runs the task dispatcher
diff --git a/macros/src/codegen/util.rs b/macros/src/codegen/util.rs
index 7a12f23e..6589f62d 100644
--- a/macros/src/codegen/util.rs
+++ b/macros/src/codegen/util.rs
@@ -106,8 +106,8 @@ pub fn is_exception(name: &Ident) -> bool {
     )
 }
 
-/// Mangle an ident
-pub fn mangle_ident(ident: &Ident) -> Ident {
+/// Mark an ident as internal
+pub fn mark_internal_ident(ident: &Ident) -> Ident {
     Ident::new(
         &format!("__rtic_internal_{}", ident.to_string()),
         Span::call_site(),
@@ -244,11 +244,6 @@ pub fn monotonic_ident(name: &str) -> Ident {
     Ident::new(&format!("MONOTONIC_STORAGE_{}", name), Span::call_site())
 }
 
-/// Generates an identifier for monotonic timer storage
-pub fn mangle_monotonic_type(name: &str) -> Ident {
-    Ident::new(&format!("MonotonicMangled{}", name), Span::call_site())
-}
-
 /// The name to get better RT flag errors
 pub fn rt_err_ident() -> Ident {
     Ident::new(
-- 
cgit v1.2.3