rust: list: hide macros from top-level kernel doc
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
@@ -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
@@ -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
@@ -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
@@ -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
Miguel Ojeda
AppliedQuoted 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 usekernel::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.Signed-off-by Gary Guo <[email protected]>
Applied to rust-next -- thanks!
Nice, this cleans up a bit further the top-level macro list in the generated docs.
Cheers,
Miguel