mirror of
https://github.com/bevyengine/bevy
synced 2024-11-22 12:43:34 +00:00
aab1f8e435
# Objective - Fixes #14697 ## Solution This PR modifies the existing `all_tuples!` macro to optionally accept a `#[doc(fake_variadic)]` attribute in its input. If the attribute is present, each invocation of the impl macro gets the correct attributes (i.e. the first impl receives `#[doc(fake_variadic)]` while the other impls are hidden using `#[doc(hidden)]`. Impls for the empty tuple (unit type) are left untouched (that's what the [standard library](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html#impl-PartialEq-for-()) and [serde](https://docs.rs/serde/latest/serde/trait.Serialize.html#impl-Serialize-for-()) do). To work around https://github.com/rust-lang/cargo/issues/8811 and to get impls on re-exports to correctly show up as variadic, `--cfg docsrs_dep` is passed when building the docs for the toplevel `bevy` crate. `#[doc(fake_variadic)]` only works on tuples and fn pointers, so impls for structs like `AnyOf<(T1, T2, ..., Tn)>` are unchanged. ## Testing I built the docs locally using `RUSTDOCFLAGS='--cfg docsrs' RUSTFLAGS='--cfg docsrs_dep' cargo +nightly doc --no-deps --workspace` and checked the documentation page of a trait both in its original crate and the re-exported version in `bevy`. The description should correctly mention for how many tuple items the trait is implemented. I added `rustc-args` for docs.rs to the `bevy` crate, I hope there aren't any other notable crates that re-export `#[doc(fake_variadic)]` traits. --- ## Showcase `bevy_ecs::query::QueryData`: <img width="1015" alt="Screenshot 2024-08-12 at 16 41 28" src="https://github.com/user-attachments/assets/d40136ed-6731-475f-91a0-9df255cd24e3"> `bevy::ecs::query::QueryData` (re-export): <img width="1005" alt="Screenshot 2024-08-12 at 16 42 57" src="https://github.com/user-attachments/assets/71d44cf0-0ab0-48b0-9a51-5ce332594e12"> ## Original Description <details> Resolves #14697 Submitting as a draft for now, very WIP. Unfortunately, the docs don't show the variadics nicely when looking at reexported items. For example: `bevy_ecs::bundle::Bundle` correctly shows the variadic impl:  while `bevy::ecs::bundle::Bundle` (the reexport) shows all the impls (not good):  Built using `RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc --workspace --no-deps` (`--no-deps` because of wgpu-core). Maybe I missed something or this is a limitation in the *totally not private* `#[doc(fake_variadic)]` thingy. In any case I desperately need some sleep now :)) </details> |
||
|---|---|---|
| .. | ||
| bevy_a11y | ||
| bevy_animation | ||
| bevy_app | ||
| bevy_asset | ||
| bevy_audio | ||
| bevy_color | ||
| bevy_core | ||
| bevy_core_pipeline | ||
| bevy_derive | ||
| bevy_dev_tools | ||
| bevy_diagnostic | ||
| bevy_dylib | ||
| bevy_ecs | ||
| bevy_encase_derive | ||
| bevy_gilrs | ||
| bevy_gizmos | ||
| bevy_gltf | ||
| bevy_hierarchy | ||
| bevy_input | ||
| bevy_internal | ||
| bevy_log | ||
| bevy_macro_utils | ||
| bevy_math | ||
| bevy_mikktspace | ||
| bevy_pbr | ||
| bevy_picking | ||
| bevy_ptr | ||
| bevy_reflect | ||
| bevy_render | ||
| bevy_scene | ||
| bevy_sprite | ||
| bevy_state | ||
| bevy_tasks | ||
| bevy_text | ||
| bevy_time | ||
| bevy_transform | ||
| bevy_ui | ||
| bevy_utils | ||
| bevy_window | ||
| bevy_winit | ||