From f6b0d18e24d49e5ecdcd18393c9c3109441a83e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sun, 22 Jan 2023 00:26:09 +0100 Subject: [PATCH] Improve RTIC doc handling Enable use of ``` #![deny(missing_docs)] ``` --- macros/src/codegen.rs | 2 +- macros/src/codegen/hardware_tasks.rs | 4 ++++ macros/src/codegen/idle.rs | 2 ++ macros/src/codegen/init.rs | 10 +++++++--- macros/src/codegen/local_resources_struct.rs | 5 ++++- macros/src/codegen/module.rs | 19 ++++++++++++++----- macros/src/codegen/shared_resources_struct.rs | 15 ++++++++++++++- macros/src/codegen/software_tasks.rs | 2 ++ 8 files changed, 48 insertions(+), 11 deletions(-) diff --git a/macros/src/codegen.rs b/macros/src/codegen.rs index 01be1d5787..9c444fed36 100644 --- a/macros/src/codegen.rs +++ b/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)* diff --git a/macros/src/codegen/hardware_tasks.rs b/macros/src/codegen/hardware_tasks.rs index f75c71d43f..780cc7e3cc 100644 --- a/macros/src/codegen/hardware_tasks.rs +++ b/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) { diff --git a/macros/src/codegen/idle.rs b/macros/src/codegen/idle.rs index 83b85d7ba6..55b7e6230f 100644 --- a/macros/src/codegen/idle.rs +++ b/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 _; diff --git a/macros/src/codegen/init.rs b/macros/src/codegen/init.rs index eaf7f612a9..e8a9c8b98c 100644 --- a/macros/src/codegen/init.rs +++ b/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())); }; diff --git a/macros/src/codegen/local_resources_struct.rs b/macros/src/codegen/local_resources_struct.rs index b7eae3f9d3..74bdbf8b89 100644 --- a/macros/src/codegen/local_resources_struct.rs +++ b/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,)* diff --git a/macros/src/codegen/module.rs b/macros/src/codegen/module.rs index fd8137fad4..d05784d18b 100644 --- a/macros/src/codegen/module.rs +++ b/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 diff --git a/macros/src/codegen/shared_resources_struct.rs b/macros/src/codegen/shared_resources_struct.rs index 90cbc1beef..7b6cd20d5c 100644 --- a/macros/src/codegen/shared_resources_struct.rs +++ b/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 { diff --git a/macros/src/codegen/software_tasks.rs b/macros/src/codegen/software_tasks.rs index 77559493bc..7c3f70fb30 100644 --- a/macros/src/codegen/software_tasks.rs +++ b/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)]