[PATCH] rust: list: hide macros from top-level kernel doc

[PATCH] rust: list: hide macros from top-level kernel doc

[Gary Guo]

From: Gary Guo <gary@garyguo.net>

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.

Signed-off-by: Gary Guo <gary@garyguo.net>
---
 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(-)

diff --git a/rust/kernel/list.rs b/rust/kernel/list.rs
index 8349ff32fc37..406e3a028c55 100644
--- a/rust/kernel/list.rs
+++ b/rust/kernel/list.rs
@@ -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.
 ///
diff --git a/rust/kernel/list/arc.rs b/rust/kernel/list/arc.rs
index 2282f33913ee..e1082423909c 100644
--- a/rust/kernel/list/arc.rs
+++ b/rust/kernel/list/arc.rs
@@ -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 {
diff --git a/rust/kernel/list/arc_field.rs b/rust/kernel/list/arc_field.rs
index c4b9dd503982..2ad8aea55993 100644
--- a/rust/kernel/list/arc_field.rs
+++ b/rust/kernel/list/arc_field.rs
@@ -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)*
diff --git a/rust/kernel/list/impl_list_item_mod.rs b/rust/kernel/list/impl_list_item_mod.rs
index ee53d0387e63..5a3eac9f3cf0 100644
--- a/rust/kernel/list/impl_list_item_mod.rs
+++ b/rust/kernel/list/impl_list_item_mod.rs
@@ -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 {

-- 
2.51.2

Re: [PATCH] rust: list: hide macros from top-level kernel doc

[Miguel Ojeda]

On Thu, Mar 12, 2026 at 6:47 PM Gary Guo <gary@kernel.org> wrote:
>
> From: Gary Guo <gary@garyguo.net>
>
> 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.
>
> Signed-off-by: Gary Guo <gary@garyguo.net>

Applied to `rust-next` -- thanks!

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

Cheers,
Miguel