Merge #689

bors[bot] · AfoHT · web-flow · commit b0bda53e4e65 · 2023-01-22T06:57:56.000Z
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 &lt;henrik@tjaders.com&gt;
diff --git 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.
 
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2,6 +2,8 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+// pool!() generates a struct without docs
+//#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2,6 +2,7 @@
 
 #![deny(unsafe_code)]
 #![deny(warnings)]
+#![deny(missing_docs)]
 #![no_main]
 #![no_std]
 
diff --git 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
diff --git a/macros/src/codegen/idle.rs b/macros/src/codegen/idle.rs
diff --git a/macros/src/codegen/init.rs b/macros/src/codegen/init.rs
diff --git a/macros/src/codegen/local_resources_struct.rs b/macros/src/codegen/local_resources_struct.rs
diff --git a/macros/src/codegen/module.rs b/macros/src/codegen/module.rs
diff --git a/macros/src/codegen/shared_resources_struct.rs b/macros/src/codegen/shared_resources_struct.rs
diff --git a/macros/src/codegen/software_tasks.rs b/macros/src/codegen/software_tasks.rs
