From a644ac73f728fde32ae95047385cc2206ccdea1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tau=20G=C3=A4rtli?= Date: Sun, 27 Oct 2024 20:01:50 +0100 Subject: [PATCH] More `#[doc(fake_variadic)]` goodness (#16108) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR adds `#[doc(fake_variadic)]` to that were previously not supported by rustdoc. Thanks to an [upstream contribution](https://github.com/rust-lang/rust/pull/132115) by yours truly, `#[doc(fake_variadic)]` is now supported on impls such as `impl QueryData for AnyOf<(T, ...)>` 🎉 Requires the latest nightly compiler (2024-10-25) which is already available on [docs.rs](https://docs.rs/about/builds). ![image](https://github.com/user-attachments/assets/68589c7e-f68f-44fb-9a7b-09d24ccf19c9) ![image](https://github.com/user-attachments/assets/f09d20d6-d89b-471b-9a81-4a72c8968178) This means that the impl sections for `QueryData` and `QueryFilter` are now nice and tidy ✨ --- I also added `fake_variadic` to some impls that use `all_tuples_with_size`, however I'm not entirely happy because the docs are slightly misleading now: ![image](https://github.com/user-attachments/assets/fac93d08-dc02-430f-9f34-c97456256c56) Note that the docs say `IntoBindGroupLayoutEntryBuilderArray<1>` instead of `IntoBindGroupLayoutEntryBuilderArray`. --- crates/bevy_ecs/src/query/fetch.rs | 15 +++++++++--- crates/bevy_ecs/src/query/filter.rs | 24 +++++++++++++++---- crates/bevy_ecs/src/system/function_system.rs | 11 +++++++-- crates/bevy_render/src/render_graph/node.rs | 12 ++++++++-- .../src/render_resource/bind_group_entries.rs | 12 ++++++++-- .../bind_group_layout_entries.rs | 12 ++++++++-- crates/bevy_utils/macros/src/lib.rs | 9 +++++-- 7 files changed, 78 insertions(+), 17 deletions(-) diff --git a/crates/bevy_ecs/src/query/fetch.rs b/crates/bevy_ecs/src/query/fetch.rs index 75c551e53f4e3..de3796190f172 100644 --- a/crates/bevy_ecs/src/query/fetch.rs +++ b/crates/bevy_ecs/src/query/fetch.rs @@ -2030,8 +2030,8 @@ macro_rules! impl_tuple_query_data { } macro_rules! impl_anytuple_fetch { - ($(($name: ident, $state: ident)),*) => { - + ($(#[$meta:meta])* $(($name: ident, $state: ident)),*) => { + $(#[$meta])* #[allow(non_snake_case)] #[allow(clippy::unused_unit)] /// SAFETY: @@ -2153,6 +2153,7 @@ macro_rules! impl_anytuple_fetch { } } + $(#[$meta])* #[allow(non_snake_case)] #[allow(clippy::unused_unit)] // SAFETY: defers to soundness of `$name: WorldQuery` impl @@ -2160,6 +2161,7 @@ macro_rules! impl_anytuple_fetch { type ReadOnly = AnyOf<($($name::ReadOnly,)*)>; } + $(#[$meta])* /// SAFETY: each item in the tuple is read only unsafe impl<$($name: ReadOnlyQueryData),*> ReadOnlyQueryData for AnyOf<($($name,)*)> {} }; @@ -2173,7 +2175,14 @@ all_tuples!( F, S ); -all_tuples!(impl_anytuple_fetch, 0, 15, F, S); +all_tuples!( + #[doc(fake_variadic)] + impl_anytuple_fetch, + 0, + 15, + F, + S +); /// [`WorldQuery`] used to nullify queries by turning `Query` into `Query>` /// diff --git a/crates/bevy_ecs/src/query/filter.rs b/crates/bevy_ecs/src/query/filter.rs index 024332b914294..ff73d6ca50016 100644 --- a/crates/bevy_ecs/src/query/filter.rs +++ b/crates/bevy_ecs/src/query/filter.rs @@ -379,7 +379,8 @@ impl Clone for OrFetch<'_, T> { } macro_rules! impl_or_query_filter { - ($(($filter: ident, $state: ident)),*) => { + ($(#[$meta:meta])* $(($filter: ident, $state: ident)),*) => { + $(#[$meta])* #[allow(unused_variables)] #[allow(non_snake_case)] #[allow(clippy::unused_unit)] @@ -497,6 +498,7 @@ macro_rules! impl_or_query_filter { } } + $(#[$meta])* // SAFETY: This only performs access that subqueries perform, and they impl `QueryFilter` and so perform no mutable access. unsafe impl<$($filter: QueryFilter),*> QueryFilter for Or<($($filter,)*)> { const IS_ARCHETYPAL: bool = true $(&& $filter::IS_ARCHETYPAL)*; @@ -546,7 +548,14 @@ all_tuples!( 15, F ); -all_tuples!(impl_or_query_filter, 0, 15, F, S); +all_tuples!( + #[doc(fake_variadic)] + impl_or_query_filter, + 0, + 15, + F, + S +); /// A filter on a component that only retains results the first time after they have been added. /// @@ -1044,7 +1053,8 @@ macro_rules! impl_archetype_filter_tuple { } macro_rules! impl_archetype_or_filter_tuple { - ($($filter: ident),*) => { + ($(#[$meta:meta])* $($filter: ident),*) => { + $(#[$meta])* impl<$($filter: ArchetypeFilter),*> ArchetypeFilter for Or<($($filter,)*)> {} }; } @@ -1057,4 +1067,10 @@ all_tuples!( F ); -all_tuples!(impl_archetype_or_filter_tuple, 0, 15, F); +all_tuples!( + #[doc(fake_variadic)] + impl_archetype_or_filter_tuple, + 0, + 15, + F +); diff --git a/crates/bevy_ecs/src/system/function_system.rs b/crates/bevy_ecs/src/system/function_system.rs index f64f83f8354f6..78f310ccc7986 100644 --- a/crates/bevy_ecs/src/system/function_system.rs +++ b/crates/bevy_ecs/src/system/function_system.rs @@ -306,7 +306,8 @@ pub struct SystemState { // So, generate a function for each arity with an explicit `FnMut` constraint to enable higher-order lifetimes, // along with a regular `SystemParamFunction` constraint to allow the system to be built. macro_rules! impl_build_system { - ($($param: ident),*) => { + ($(#[$meta:meta])* $($param: ident),*) => { + $(#[$meta])* impl<$($param: SystemParam),*> SystemState<($($param,)*)> { /// Create a [`FunctionSystem`] from a [`SystemState`]. /// This method signature allows type inference of closure parameters for a system with no input. @@ -344,7 +345,13 @@ macro_rules! impl_build_system { } } -all_tuples!(impl_build_system, 0, 16, P); +all_tuples!( + #[doc(fake_variadic)] + impl_build_system, + 0, + 16, + P +); impl SystemState { /// Creates a new [`SystemState`] with default state. diff --git a/crates/bevy_render/src/render_graph/node.rs b/crates/bevy_render/src/render_graph/node.rs index 1e0243e31cdff..c8469ee9aecea 100644 --- a/crates/bevy_render/src/render_graph/node.rs +++ b/crates/bevy_render/src/render_graph/node.rs @@ -36,7 +36,8 @@ pub trait IntoRenderNodeArray { } macro_rules! impl_render_label_tuples { - ($N: expr, $(($T: ident, $I: ident)),*) => { + ($N: expr, $(#[$meta:meta])* $(($T: ident, $I: ident)),*) => { + $(#[$meta])* impl<$($T: RenderLabel),*> IntoRenderNodeArray<$N> for ($($T,)*) { #[inline] fn into_array(self) -> [InternedRenderLabel; $N] { @@ -47,7 +48,14 @@ macro_rules! impl_render_label_tuples { } } -all_tuples_with_size!(impl_render_label_tuples, 1, 32, T, l); +all_tuples_with_size!( + #[doc(fake_variadic)] + impl_render_label_tuples, + 1, + 32, + T, + l +); /// A render node that can be added to a [`RenderGraph`](super::RenderGraph). /// diff --git a/crates/bevy_render/src/render_resource/bind_group_entries.rs b/crates/bevy_render/src/render_resource/bind_group_entries.rs index 6319e168bd955..298a4e41fd5a1 100644 --- a/crates/bevy_render/src/render_resource/bind_group_entries.rs +++ b/crates/bevy_render/src/render_resource/bind_group_entries.rs @@ -180,7 +180,8 @@ pub trait IntoBindingArray<'b, const N: usize> { } macro_rules! impl_to_binding_slice { - ($N: expr, $(($T: ident, $I: ident)),*) => { + ($N: expr, $(#[$meta:meta])* $(($T: ident, $I: ident)),*) => { + $(#[$meta])* impl<'b, $($T: IntoBinding<'b>),*> IntoBindingArray<'b, $N> for ($($T,)*) { #[inline] fn into_array(self) -> [BindingResource<'b>; $N] { @@ -191,7 +192,14 @@ macro_rules! impl_to_binding_slice { } } -all_tuples_with_size!(impl_to_binding_slice, 1, 32, T, s); +all_tuples_with_size!( + #[doc(fake_variadic)] + impl_to_binding_slice, + 1, + 32, + T, + s +); pub trait IntoIndexedBindingArray<'b, const N: usize> { fn into_array(self) -> [(u32, BindingResource<'b>); N]; diff --git a/crates/bevy_render/src/render_resource/bind_group_layout_entries.rs b/crates/bevy_render/src/render_resource/bind_group_layout_entries.rs index 346019a2fb272..45f4c26c6cd22 100644 --- a/crates/bevy_render/src/render_resource/bind_group_layout_entries.rs +++ b/crates/bevy_render/src/render_resource/bind_group_layout_entries.rs @@ -242,7 +242,8 @@ pub trait IntoBindGroupLayoutEntryBuilderArray { fn into_array(self) -> [BindGroupLayoutEntryBuilder; N]; } macro_rules! impl_to_binding_type_slice { - ($N: expr, $(($T: ident, $I: ident)),*) => { + ($N: expr, $(#[$meta:meta])* $(($T: ident, $I: ident)),*) => { + $(#[$meta])* impl<$($T: IntoBindGroupLayoutEntryBuilder),*> IntoBindGroupLayoutEntryBuilderArray<$N> for ($($T,)*) { #[inline] fn into_array(self) -> [BindGroupLayoutEntryBuilder; $N] { @@ -252,7 +253,14 @@ macro_rules! impl_to_binding_type_slice { } } } -all_tuples_with_size!(impl_to_binding_type_slice, 1, 32, T, s); +all_tuples_with_size!( + #[doc(fake_variadic)] + impl_to_binding_type_slice, + 1, + 32, + T, + s +); pub trait IntoIndexedBindGroupLayoutEntryBuilderArray { fn into_array(self) -> [(u32, BindGroupLayoutEntryBuilder); N]; diff --git a/crates/bevy_utils/macros/src/lib.rs b/crates/bevy_utils/macros/src/lib.rs index b5404d078df5f..d6b9cb1d83eae 100644 --- a/crates/bevy_utils/macros/src/lib.rs +++ b/crates/bevy_utils/macros/src/lib.rs @@ -315,9 +315,14 @@ pub fn all_tuples_with_size(input: TokenStream) -> TokenStream { } let macro_ident = &input.macro_ident; let invocations = (input.start..=input.end).map(|i| { - let ident_tuples = &ident_tuples[..i]; + let ident_tuples = choose_ident_tuples(&input, &ident_tuples, i); + let attrs = if input.fake_variadic { + fake_variadic_attrs(len, i) + } else { + TokenStream2::default() + }; quote! { - #macro_ident!(#i, #(#ident_tuples),*); + #macro_ident!(#i, #attrs #ident_tuples); } }); TokenStream::from(quote! {