From 40d5ace1112e7cc7ce8fc841ae59fb90c3c310f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sat, 21 Jan 2023 23:10:43 +0100 Subject: [PATCH 1/5] Deny missing_docs for all examples --- examples/binds.rs | 1 + examples/cancel-reschedule.rs | 1 + examples/capacity.rs | 1 + examples/cfg-whole-task.rs | 1 + examples/common.rs | 1 + examples/complex.rs | 1 + examples/declared_locals.rs | 1 + examples/destructure.rs | 1 + examples/extern_binds.rs | 1 + examples/extern_spawn.rs | 1 + examples/generics.rs | 1 + examples/hardware.rs | 1 + examples/idle-wfi.rs | 1 + examples/idle.rs | 1 + examples/init.rs | 1 + examples/locals.rs | 5 +++++ examples/lock-free.rs | 1 + examples/lock.rs | 1 + examples/message.rs | 1 + examples/message_passing.rs | 1 + examples/multilock.rs | 1 + examples/not-sync.rs | 4 ++++ examples/only-shared-access.rs | 1 + examples/periodic-at.rs | 1 + examples/periodic-at2.rs | 1 + examples/periodic.rs | 1 + examples/peripherals-taken.rs | 4 +++- examples/pool.rs | 1 + examples/ramfunc.rs | 1 + examples/resource-user-struct.rs | 1 + examples/schedule.rs | 1 + examples/shared.rs | 3 +++ examples/spawn.rs | 1 + examples/static.rs | 1 + examples/t-binds.rs | 1 + examples/t-htask-main.rs | 2 ++ examples/t-idle-main.rs | 2 ++ examples/t-schedule.rs | 1 + examples/t-spawn.rs | 1 + examples/task.rs | 1 + 40 files changed, 53 insertions(+), 1 deletion(-) diff --git a/examples/binds.rs b/examples/binds.rs index 601f245a0c..1b0c8c5beb 100644 --- a/examples/binds.rs +++ b/examples/binds.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/cancel-reschedule.rs b/examples/cancel-reschedule.rs index 7ab437f272..36c496b71a 100644 --- a/examples/cancel-reschedule.rs +++ b/examples/cancel-reschedule.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/capacity.rs b/examples/capacity.rs index e625249af8..550829be32 100644 --- a/examples/capacity.rs +++ b/examples/capacity.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/cfg-whole-task.rs b/examples/cfg-whole-task.rs index 90fb9ccc9b..b5b978312e 100644 --- a/examples/cfg-whole-task.rs +++ b/examples/cfg-whole-task.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/common.rs b/examples/common.rs index 7dcc5421a9..74ee8db2c8 100644 --- a/examples/common.rs +++ b/examples/common.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/complex.rs b/examples/complex.rs index 2be71d22fb..73df025d2f 100644 --- a/examples/complex.rs +++ b/examples/complex.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/declared_locals.rs b/examples/declared_locals.rs index 52d354bc9a..cb6214960f 100644 --- a/examples/declared_locals.rs +++ b/examples/declared_locals.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/destructure.rs b/examples/destructure.rs index fd577a6c9c..70b0dd7e6f 100644 --- a/examples/destructure.rs +++ b/examples/destructure.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/extern_binds.rs b/examples/extern_binds.rs index c2186cb7fb..bfc85cfc82 100644 --- a/examples/extern_binds.rs +++ b/examples/extern_binds.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/extern_spawn.rs b/examples/extern_spawn.rs index 2eec2dbc49..446d31a77b 100644 --- a/examples/extern_spawn.rs +++ b/examples/extern_spawn.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/generics.rs b/examples/generics.rs index 6243d562e8..bc4959fb7b 100644 --- a/examples/generics.rs +++ b/examples/generics.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/hardware.rs b/examples/hardware.rs index 590bf6ab66..a7fdb47a37 100644 --- a/examples/hardware.rs +++ b/examples/hardware.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/idle-wfi.rs b/examples/idle-wfi.rs index 42fd7b49e0..5e52620d45 100644 --- a/examples/idle-wfi.rs +++ b/examples/idle-wfi.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/idle.rs b/examples/idle.rs index ad04fd68e4..ccec9bf273 100644 --- a/examples/idle.rs +++ b/examples/idle.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/init.rs b/examples/init.rs index 7a10149692..afd3b98ce9 100644 --- a/examples/init.rs +++ b/examples/init.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/locals.rs b/examples/locals.rs index 1889775316..9e112be4b3 100644 --- a/examples/locals.rs +++ b/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, } diff --git a/examples/lock-free.rs b/examples/lock-free.rs index 32853e44ed..6e5faadbf2 100644 --- a/examples/lock-free.rs +++ b/examples/lock-free.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/lock.rs b/examples/lock.rs index 16f3b33812..5b3e0bcc3c 100644 --- a/examples/lock.rs +++ b/examples/lock.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/message.rs b/examples/message.rs index a5c89199ee..8a6a12d5f4 100644 --- a/examples/message.rs +++ b/examples/message.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/message_passing.rs b/examples/message_passing.rs index 13e3b98de3..9550a5010a 100644 --- a/examples/message_passing.rs +++ b/examples/message_passing.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/multilock.rs b/examples/multilock.rs index 83df8d7d4e..c7085cd51c 100644 --- a/examples/multilock.rs +++ b/examples/multilock.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/not-sync.rs b/examples/not-sync.rs index aa79ad5626..68af04a6c6 100644 --- a/examples/not-sync.rs +++ b/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, } diff --git a/examples/only-shared-access.rs b/examples/only-shared-access.rs index c9826d09b0..b32827abf2 100644 --- a/examples/only-shared-access.rs +++ b/examples/only-shared-access.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/periodic-at.rs b/examples/periodic-at.rs index 1116210248..ad8a5496f2 100644 --- a/examples/periodic-at.rs +++ b/examples/periodic-at.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/periodic-at2.rs b/examples/periodic-at2.rs index 35ebb52f5b..4719bdb7e4 100644 --- a/examples/periodic-at2.rs +++ b/examples/periodic-at2.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/periodic.rs b/examples/periodic.rs index 5d66735c28..13ca7c852c 100644 --- a/examples/periodic.rs +++ b/examples/periodic.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/peripherals-taken.rs b/examples/peripherals-taken.rs index d542c0e64d..cc9b9a11ce 100644 --- a/examples/peripherals-taken.rs +++ b/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] diff --git a/examples/pool.rs b/examples/pool.rs index 5014e216d3..4b9aa44223 100644 --- a/examples/pool.rs +++ b/examples/pool.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/ramfunc.rs b/examples/ramfunc.rs index 049af18fbe..956a2554d8 100644 --- a/examples/ramfunc.rs +++ b/examples/ramfunc.rs @@ -1,6 +1,7 @@ //! examples/ramfunc.rs #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/resource-user-struct.rs b/examples/resource-user-struct.rs index 39a5b16c8a..37a885609f 100644 --- a/examples/resource-user-struct.rs +++ b/examples/resource-user-struct.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/schedule.rs b/examples/schedule.rs index 58e73dad18..9b86929d93 100644 --- a/examples/schedule.rs +++ b/examples/schedule.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/shared.rs b/examples/shared.rs index 58d64e4191..b43a19a3c5 100644 --- a/examples/shared.rs +++ b/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>, } diff --git a/examples/spawn.rs b/examples/spawn.rs index 75b7f85fe8..50ae7e7a75 100644 --- a/examples/spawn.rs +++ b/examples/spawn.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/static.rs b/examples/static.rs index abeb9c525a..efafcc7aa8 100644 --- a/examples/static.rs +++ b/examples/static.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/t-binds.rs b/examples/t-binds.rs index 12479c0ad4..822a2eeabb 100644 --- a/examples/t-binds.rs +++ b/examples/t-binds.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/t-htask-main.rs b/examples/t-htask-main.rs index 37189faf76..2b17b2ee02 100644 --- a/examples/t-htask-main.rs +++ b/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] diff --git a/examples/t-idle-main.rs b/examples/t-idle-main.rs index 1adc9bf044..48635b2ab2 100644 --- a/examples/t-idle-main.rs +++ b/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] diff --git a/examples/t-schedule.rs b/examples/t-schedule.rs index 5ec420873d..f3979dd62f 100644 --- a/examples/t-schedule.rs +++ b/examples/t-schedule.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/t-spawn.rs b/examples/t-spawn.rs index 2bd771d7f6..7483a8494b 100644 --- a/examples/t-spawn.rs +++ b/examples/t-spawn.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] diff --git a/examples/task.rs b/examples/task.rs index d24fca6261..9757f2f559 100644 --- a/examples/task.rs +++ b/examples/task.rs @@ -2,6 +2,7 @@ #![deny(unsafe_code)] #![deny(warnings)] +#![deny(missing_docs)] #![no_main] #![no_std] From 1237f5b33b5ad61e94acb7f93255cb97bfb8ead6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sun, 22 Jan 2023 00:22:46 +0100 Subject: [PATCH 2/5] Heapless 0.7.16 pool!() generates undocumented struct --- examples/pool.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/pool.rs b/examples/pool.rs index 4b9aa44223..ab76370e71 100644 --- a/examples/pool.rs +++ b/examples/pool.rs @@ -2,7 +2,8 @@ #![deny(unsafe_code)] #![deny(warnings)] -#![deny(missing_docs)] +// pool!() generates a struct without docs +//#![deny(missing_docs)] #![no_main] #![no_std] 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 3/5] 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)] From 7ba23044e6992019d07f3f919233e505109eb77d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sun, 22 Jan 2023 00:30:40 +0100 Subject: [PATCH 4/5] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 612b8076fa..5bc38d83a3 100644 --- a/CHANGELOG.md +++ b/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. From 3f74f3b8459fdd451707511954a6ea3d128aabe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sun, 22 Jan 2023 00:35:03 +0100 Subject: [PATCH 5/5] Make clippy happy --- macros/src/codegen/idle.rs | 2 +- macros/src/codegen/init.rs | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/macros/src/codegen/idle.rs b/macros/src/codegen/idle.rs index 55b7e6230f..77a7f9feb2 100644 --- a/macros/src/codegen/idle.rs +++ b/macros/src/codegen/idle.rs @@ -59,7 +59,7 @@ pub fn codegen( analysis, extra, )); - let idle_doc = &format!(" User provided idle function"); + let idle_doc = " User provided idle function".to_string(); let attrs = &idle.attrs; let context = &idle.context; diff --git a/macros/src/codegen/init.rs b/macros/src/codegen/init.rs index e8a9c8b98c..34f86f2721 100644 --- a/macros/src/codegen/init.rs +++ b/macros/src/codegen/init.rs @@ -66,8 +66,8 @@ 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"); + 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 { @@ -81,7 +81,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> CodegenResult { }); let user_init_return = quote! {#shared, #local, #name::Monotonics}; - let user_init_doc = &format!(" User provided init function"); + let user_init_doc = " User provided init function".to_string(); let user_init = quote!( #(#attrs)*