More #[doc(fake_variadic)] goodness (bevyengine#16108)

This PR adds `#[doc(fake_variadic)]` to that were previously not supported by rustdoc. Thanks to an [upstream contribution](rust-lang/rust#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<N>`.
grace125 · Oct 27, 2024 · a644ac7 · a644ac7
1 parent 60b2c7c
commit a644ac7
Show file tree

Hide file tree

Showing 7 changed files with 78 additions and 17 deletions.
diff --git 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,13 +2153,15 @@ macro_rules! impl_anytuple_fetch {
             }
         }
 
+        $(#[$meta])*
         #[allow(non_snake_case)]
         #[allow(clippy::unused_unit)]
         // SAFETY: defers to soundness of `$name: WorldQuery` impl
         unsafe impl<$($name: QueryData),*> QueryData for AnyOf<($($name,)*)> {
             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<D>` into `Query<NopWorldQuery<D>>`
 ///

diff --git a/crates/bevy_ecs/src/query/filter.rs b/crates/bevy_ecs/src/query/filter.rs
@@ -379,7 +379,8 @@ impl<T: WorldQuery> 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
@@ -306,7 +306,8 @@ pub struct SystemState<Param: SystemParam + 'static> {
 // 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<Param: SystemParam> SystemState<Param> {
     /// 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
@@ -36,7 +36,8 @@ pub trait IntoRenderNodeArray<const N: usize> {
 }
 
 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
@@ -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
@@ -242,7 +242,8 @@ pub trait IntoBindGroupLayoutEntryBuilderArray<const N: usize> {
     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<const N: usize> {
     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
@@ -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! {