Improve RTIC doc handling

Enable use of

```
 #![deny(missing_docs)]
```

Author: AfoHT

macros/src/codegen.rs

@@ -187,7 +187,7 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
 
             #(#root_software_tasks)*
 
-            /// app module
+            /// App module
             #(#mod_app)*
 
             #(#mod_app_shared_resources)*

macros/src/codegen/hardware_tasks.rs

@@ -33,10 +33,12 @@ pub fn codegen(
         let priority = task.args.priority;
         let cfgs = &task.cfgs;
         let attrs = &task.attrs;
+        let user_hardware_task_isr_doc = &format!(" User HW task ISR trampoline for {name}");
 
         mod_app.push(quote!(
             #[allow(non_snake_case)]
             #[no_mangle]
+            #[doc = #user_hardware_task_isr_doc]
             #(#attrs)*
             #(#cfgs)*
             unsafe fn #symbol() {
@@ -88,11 +90,13 @@ pub fn codegen(
             extra,
         ));
 
+        let user_hardware_task_doc = &format!(" User HW task: {name}");
         if !task.is_extern {
             let attrs = &task.attrs;
             let context = &task.context;
             let stmts = &task.stmts;
             user_tasks.push(quote!(
+                #[doc = #user_hardware_task_doc]
                 #(#attrs)*
                 #[allow(non_snake_case)]
                 fn #name(#context: #name::Context) {

macros/src/codegen/idle.rs

@@ -59,12 +59,14 @@ pub fn codegen(
             analysis,
             extra,
         ));
+        let idle_doc = &format!(" User provided idle function");
 
         let attrs = &idle.attrs;
         let context = &idle.context;
         let stmts = &idle.stmts;
         let user_idle = Some(quote!(
             #(#attrs)*
+            #[doc = #idle_doc]
             #[allow(non_snake_case)]
             fn #name(#context: #name::Context) -> ! {
                 use rtic::Mutex as _;

macros/src/codegen/init.rs

@@ -65,22 +65,27 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> CodegenResult {
             )
         })
         .collect();
+
+    let shared_resources_doc = &format!(" RTIC shared resource struct");
+    let local_resources_doc = &format!(" RTIC local resource struct");
     root_init.push(quote! {
+        #[doc = #shared_resources_doc]
         struct #shared {
             #(#shared_resources)*
         }
 
+        #[doc = #local_resources_doc]
         struct #local {
             #(#local_resources)*
         }
     });
 
-    // let locals_pat = locals_pat.iter();
-
     let user_init_return = quote! {#shared, #local, #name::Monotonics};
+    let user_init_doc = &format!(" User provided init function");
 
     let user_init = quote!(
         #(#attrs)*
+        #[doc = #user_init_doc]
         #[inline(always)]
         #[allow(non_snake_case)]
         fn #name(#context: #name::Context) -> (#user_init_return) {
@@ -100,7 +105,6 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> CodegenResult {
         mod_app = Some(constructor);
     }
 
-    // let locals_new = locals_new.iter();
     let call_init = quote! {
         let (shared_resources, local_resources, mut monotonics) = #name(#name::Context::new(core.into()));
     };

macros/src/codegen/local_resources_struct.rs

@@ -49,7 +49,9 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
             util::declared_static_local_resource_ident(name, &task_name)
         };
 
+        let local_resource_doc = format!(" Local resource `{name}`");
         fields.push(quote!(
+            #[doc = #local_resource_doc]
             #(#cfgs)*
             pub #name: &#lt mut #ty
         ));
@@ -82,7 +84,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
         }
     }
 
-    let doc = format!("Local resources `{}` has access to", ctxt.ident(app));
+    let doc = format!(" Local resources `{}` has access to", ctxt.ident(app));
     let ident = util::local_resources_ident(ctxt, app);
     let item = quote!(
         #[allow(non_snake_case)]
@@ -96,6 +98,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
     let constructor = quote!(
         impl<#lt> #ident<#lt> {
             #[inline(always)]
+            #[doc(hidden)]
             pub unsafe fn new() -> Self {
                 #ident {
                     #(#values,)*

macros/src/codegen/module.rs

@@ -133,15 +133,16 @@ pub fn codegen(
         ));
 
         module_items.push(quote!(
+            #[doc(inline)]
             pub use super::#internal_monotonics_ident as Monotonics;
         ));
     }
 
     let doc = match ctxt {
-        Context::Idle => "Idle loop",
-        Context::Init => "Initialization function",
-        Context::HardwareTask(_) => "Hardware task",
-        Context::SoftwareTask(_) => "Software task",
+        Context::Idle => " Idle loop",
+        Context::Init => " Initialization function",
+        Context::HardwareTask(_) => " Hardware task",
+        Context::SoftwareTask(_) => " Software task",
     };
 
     let v = Vec::new();
@@ -172,8 +173,8 @@ pub fn codegen(
     let internal_context_name = util::internal_task_ident(name, "Context");
 
     items.push(quote!(
-        #(#cfgs)*
         /// Execution context
+        #(#cfgs)*
         #[allow(non_snake_case)]
         #[allow(non_camel_case_types)]
         pub struct #internal_context_name<#lt> {
@@ -182,6 +183,7 @@ pub fn codegen(
 
         #(#cfgs)*
         impl<#lt> #internal_context_name<#lt> {
+            #[doc(hidden)]
             #[inline(always)]
             pub unsafe fn new(#core #priority) -> Self {
                 #internal_context_name {
@@ -192,6 +194,7 @@ pub fn codegen(
     ));
 
     module_items.push(quote!(
+        #[doc(inline)]
         #(#cfgs)*
         pub use super::#internal_context_name as Context;
     ));
@@ -251,6 +254,7 @@ pub fn codegen(
         }));
 
         module_items.push(quote!(
+            #[doc(inline)]
             #(#cfgs)*
             pub use super::#internal_spawn_ident as spawn;
         ));
@@ -300,6 +304,7 @@ pub fn codegen(
                 ));
             }
             module_items.push(quote!(
+                #[doc(hidden)]
                 pub mod #m {
                     pub use super::super::#internal_spawn_after_ident as spawn_after;
                     pub use super::super::#internal_spawn_at_ident as spawn_at;
@@ -308,6 +313,7 @@ pub fn codegen(
             ));
 
             items.push(quote!(
+                #[doc(hidden)]
                 #(#cfgs)*
                 #[allow(non_snake_case)]
                 #[allow(non_camel_case_types)]
@@ -317,6 +323,7 @@ pub fn codegen(
                 }
 
                 impl core::fmt::Debug for #internal_spawn_handle_ident {
+                    #[doc(hidden)]
                     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                         f.debug_struct(#spawn_handle_string).finish()
                     }
@@ -344,6 +351,7 @@ pub fn codegen(
                         })
                     }
 
+                    /// Reschedule after 
                     #[inline]
                     pub fn reschedule_after(
                         self,
@@ -352,6 +360,7 @@ pub fn codegen(
                         self.reschedule_at(monotonics::#m::now() + duration)
                     }
 
+                    /// Reschedule at 
                     pub fn reschedule_at(
                         self,
                         instant: <#m as rtic::Monotonic>::Instant

macros/src/codegen/shared_resources_struct.rs

@@ -44,27 +44,35 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
                 quote!('a)
             };
 
+            let lock_free_resource_doc = format!(" Lock free resource `{name}`");
             fields.push(quote!(
+                #[doc = #lock_free_resource_doc]
                 #(#cfgs)*
                 pub #name: &#lt #mut_ #ty
             ));
         } else if access.is_shared() {
             lt = Some(quote!('a));
 
+            let shared_resource_doc = format!(" Shared resource `{name}`");
             fields.push(quote!(
+                #[doc = #shared_resource_doc]
                 #(#cfgs)*
                 pub #name: &'a #ty
             ));
         } else {
             // Resource proxy
             lt = Some(quote!('a));
 
+            let resource_doc =
+                format!(" Resource proxy resource `{name}`. Use method `.lock()` to gain access");
             fields.push(quote!(
+                #[doc = #resource_doc]
                 #(#cfgs)*
                 pub #name: shared_resources::#shared_name<'a>
             ));
 
             values.push(quote!(
+                #[doc(hidden)]
                 #(#cfgs)*
                 #name: shared_resources::#shared_name::new(priority)
 
@@ -74,13 +82,17 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
             continue;
         }
 
+        let resource_doc;
         let expr = if access.is_exclusive() {
+            resource_doc = format!(" Exclusive access resource `{name}`");
             quote!(&mut *(&mut *#mangled_name.get_mut()).as_mut_ptr())
         } else {
+            resource_doc = format!(" Non-exclusive access resource `{name}`");
             quote!(&*(&*#mangled_name.get()).as_ptr())
         };
 
         values.push(quote!(
+            #[doc = #resource_doc]
             #(#cfgs)*
             #name: #expr
         ));
@@ -100,7 +112,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
         }
     }
 
-    let doc = format!("Shared resources `{}` has access to", ctxt.ident(app));
+    let doc = format!(" Shared resources `{}` has access to", ctxt.ident(app));
     let ident = util::shared_resources_ident(ctxt, app);
     let item = quote!(
         #[allow(non_snake_case)]
@@ -118,6 +130,7 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
     };
     let constructor = quote!(
         impl<#lt> #ident<#lt> {
+            #[doc(hidden)]
             #[inline(always)]
             pub unsafe fn new(#arg) -> Self {
                 #ident {

macros/src/codegen/software_tasks.rs

@@ -125,7 +125,9 @@ pub fn codegen(
             let attrs = &task.attrs;
             let cfgs = &task.cfgs;
             let stmts = &task.stmts;
+            let user_task_doc = format!(" User SW task {name}");
             user_tasks.push(quote!(
+                #[doc = #user_task_doc]
                 #(#attrs)*
                 #(#cfgs)*
                 #[allow(non_snake_case)]