Skip to contentSkip to conversation

rust: list: hide macros from top-level kernel doc

PATCH Applied Gary Guo 2 participants 2 messages Mar 12 – Mar 27 Rust

lore
Share & tools
lore

Gary Guo

author
#0 lore raw

PATCH 1/1 rust: list: hide macros from top-level kernel doc

From: Gary Guo <[email protected]>

Due to Rust macro scoping rules, all macros defined in a crate using #[macro_export] end up in the top-level. For the list macros, we re-export them inside the list module, and expect users to use kernel::list::macro_name!().

Use #[doc(hidden)] on the macro definition, and use #[doc(inline)] on the re-export to make the macro appear to be defined at module-level inside documentation.

The other exported types are already automatically #[doc(inline)] because they are defined in a non-public module, so there is no need to split the macro re-exports out.

---
 rust/kernel/list.rs                    | 22 +++++++++++++++++++---
 rust/kernel/list/arc.rs                |  1 +
 rust/kernel/list/arc_field.rs          |  1 +
 rust/kernel/list/impl_list_item_mod.rs |  3 +++
 4 files changed, 24 insertions(+), 3 deletions(-)
rust/kernel/list.rs +19 -3
index 8349ff32fc37..406e3a028c55 100644
@@ -12,15 +12,31 @@
 use pin_init::PinInit;
 
 mod impl_list_item_mod;
+#[doc(inline)]
 pub use self::impl_list_item_mod::{
-    impl_has_list_links, impl_has_list_links_self_ptr, impl_list_item, HasListLinks, HasSelfPtr,
+    impl_has_list_links,
+    impl_has_list_links_self_ptr,
+    impl_list_item,
+    HasListLinks,
+    HasSelfPtr, //
 };
 
 mod arc;
-pub use self::arc::{impl_list_arc_safe, AtomicTracker, ListArc, ListArcSafe, TryNewListArc};
+#[doc(inline)]
+pub use self::arc::{
+    impl_list_arc_safe,
+    AtomicTracker,
+    ListArc,
+    ListArcSafe,
+    TryNewListArc, //
+};
 
 mod arc_field;
-pub use self::arc_field::{define_list_arc_field_getter, ListArcField};
+#[doc(inline)]
+pub use self::arc_field::{
+    define_list_arc_field_getter,
+    ListArcField, //
+};
 
 /// A linked list.
 ///
rust/kernel/list/arc.rs +1 -0
index 2282f33913ee..e1082423909c 100644
@@ -82,6 +82,7 @@ pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
 /// [`AtomicTracker`]. However, it is also possible to defer the tracking to another struct
 /// using also using this macro.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! impl_list_arc_safe {
     (impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
         impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
rust/kernel/list/arc_field.rs +1 -0
index c4b9dd503982..2ad8aea55993 100644
@@ -66,6 +66,7 @@ pub unsafe fn assert_mut(&self) -> &mut T {
 
 /// Defines getters for a [`ListArcField`].
 #[macro_export]
+#[doc(hidden)]
 macro_rules! define_list_arc_field_getter {
     ($pub:vis fn $name:ident(&self $(<$id:tt>)?) -> &$typ:ty { $field:ident }
      $($rest:tt)*
rust/kernel/list/impl_list_item_mod.rs +3 -0
index ee53d0387e63..5a3eac9f3cf0 100644
@@ -29,6 +29,7 @@ pub unsafe trait HasListLinks<const ID: u64 = 0> {
 
 /// Implements the [`HasListLinks`] trait for the given type.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! impl_has_list_links {
     ($(impl$({$($generics:tt)*})?
        HasListLinks$(<$id:tt>)?
@@ -74,6 +75,7 @@ pub unsafe trait HasSelfPtr<T: ?Sized, const ID: u64 = 0>
 
 /// Implements the [`HasListLinks`] and [`HasSelfPtr`] traits for the given type.
 #[macro_export]
+#[doc(hidden)]
 macro_rules! impl_has_list_links_self_ptr {
     ($(impl$({$($generics:tt)*})?
        HasSelfPtr<$item_type:ty $(, $id:tt)?>
@@ -181,6 +183,7 @@ unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$
 /// }
 /// ```
 #[macro_export]
+#[doc(hidden)]
 macro_rules! impl_list_item {
     (
         $(impl$({$($generics:tt)*})? ListItem<$num:tt> for $self:ty {
Signature · 1 line
2.51.2
Applied
#1 lore raw
Quoted 12 lines · Gary Guo

From: Gary Guo <[email protected]>

Due to Rust macro scoping rules, all macros defined in a crate using #[macro_export] end up in the top-level. For the list macros, we re-export them inside the list module, and expect users to use kernel::list::macro_name!().

Use #[doc(hidden)] on the macro definition, and use #[doc(inline)] on the re-export to make the macro appear to be defined at module-level inside documentation.

Quoted 5 lines

The other exported types are already automatically #[doc(inline)] because they are defined in a non-public module, so there is no need to split the macro re-exports out.

Applied to rust-next -- thanks!

Nice, this cleans up a bit further the top-level macro list in the generated docs.

Cheers,
Miguel