mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-11-25 21:19:35 +01:00
Code Issues Projects Releases Packages Wiki Activity

Improve RTIC doc handling

Browse source 
Enable use of

```
 #![deny(missing_docs)]
```
This commit is contained in:
Henrik Tjäder 2023-01-22 00:26:09 +01:00
parent 1237f5b33b
commit f6b0d18e24
8 changed files with 48 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
macros/src/codegen.rs
View file

@ -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)*

4
macros/src/codegen/hardware_tasks.rs
View file

@ -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) {

2
macros/src/codegen/idle.rs
View file

@ -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 _;

10
macros/src/codegen/init.rs
View file

@ -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()));
};

5
macros/src/codegen/local_resources_struct.rs
View file

@ -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,)*

19
macros/src/codegen/module.rs
View file

@ -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

15
macros/src/codegen/shared_resources_struct.rs
View file

@ -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 {

2
macros/src/codegen/software_tasks.rs
View file

@ -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)]