Merge #689

689: Missing docs: Improve #[doc] generation r=korken89 a=AfoHT

Improve RTIC doc handling

Enable use of

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

and makes the cargo doc output more useful

Co-authored-by: Henrik Tjäder <henrik@tjaders.com>

CHANGELOG.md

@@ -14,6 +14,7 @@ For each category, *Added*, *Changed*, *Fixed* add new entries at the top!
 
 ### Fixed
 
+- Attempt to handle docs generation enabling `deny(missing_docs)`
 - Use native GHA rustup and cargo
 - Distinguish between thumbv8m.base and thumbv8m.main for basepri usage.
 

examples/binds.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/cancel-reschedule.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/capacity.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/cfg-whole-task.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/common.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/complex.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/declared_locals.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/destructure.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/extern_binds.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/extern_spawn.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/generics.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/hardware.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/idle-wfi.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/idle.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/init.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/locals.rs

@@ -2,6 +2,8 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 
@@ -16,8 +18,11 @@ mod app {
 
     #[local]
     struct Local {
+        /// Local foo
         local_to_foo: i64,
+        /// Local bar
         local_to_bar: i64,
+        /// Local idle
         local_to_idle: i64,
     }
 

examples/lock-free.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/lock.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/message.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/message_passing.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/multilock.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/not-sync.rs

@@ -2,13 +2,16 @@
 
 // #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 
 use core::marker::PhantomData;
 use panic_semihosting as _;
 
+/// Not sync
 pub struct NotSync {
+    /// Phantom action
     _0: PhantomData<*const ()>,
 }
 
@@ -22,6 +25,7 @@ mod app {
 
     #[shared]
     struct Shared {
+        /// This resource is not Sync
         shared: NotSync,
     }
 

examples/only-shared-access.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/periodic-at.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/periodic-at2.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/periodic.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/peripherals-taken.rs

@@ -1,5 +1,7 @@
-#![deny(unsafe_code)]
+//! examples/peripherals-taken.rs
 #![deny(warnings)]
+#![deny(unsafe_code)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/pool.rs

@@ -2,6 +2,8 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+// pool!() generates a struct without docs
+//#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/ramfunc.rs

@@ -1,6 +1,7 @@
 //! examples/ramfunc.rs
 
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/resource-user-struct.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/schedule.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/shared.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 
@@ -15,7 +16,9 @@ mod app {
 
     #[shared]
     struct Shared {
+        /// Producer
         p: Producer<'static, u32, 5>,
+        /// Consumer
         c: Consumer<'static, u32, 5>,
     }
 

examples/spawn.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/static.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/t-binds.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/t-htask-main.rs

@@ -1,5 +1,7 @@
+//! examples/t-htask-main.rs
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/t-idle-main.rs

@@ -1,5 +1,7 @@
+//! examples/t-idle-main.rs
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/t-schedule.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/t-spawn.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

examples/task.rs

@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 

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 = " User provided idle function".to_string();
 
         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 = " RTIC shared resource struct".to_string();
+    let local_resources_doc = " RTIC local resource struct".to_string();
     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 = " User provided init function".to_string();
 
     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::Idle => " Idle loop",
-        Context::Init => "Initialization function",
+        Context::Init => " Initialization function",
-        Context::HardwareTask(_) => "Hardware task",
+        Context::HardwareTask(_) => " Hardware task",
-        Context::SoftwareTask(_) => "Software 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,14 +44,18 @@ 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
             ));
@@ -59,12 +63,16 @@ pub fn codegen(ctxt: Context, needs_lt: &mut bool, app: &App) -> (TokenStream2,
             // 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)]