Use #[doc(fake_variadic)] to improve docs readability

[bash]

Objective

• Fixes Consider using fake_variadic to improve docs #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 and serde do).

To work around rust-lang/cargo#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:

bevy::ecs::query::QueryData (re-export):

Original Description

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 :))

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[MrGVSV]

Any reason not to include the all_tuples! usages in this block? I think it should be doable if we modify the internal macros (e.g. impl_get_ownership!, impl_from_arg!, and impl_into_return!).

[bash]

I assume because the block is gated by #[cfg(feature = "functions")]? I'm afraid that I'm the wrong person to answer this question, I saw this code for the first time :)

[alice-i-cecile]

That's a shame that re-exports don't work. IMO this isn't worth merging until that's fixed here or upstream.

[bash]

I may have found the culprit: rust-lang/cargo#8811
An "easy" workaround would be to add a rustc arg for docs.rs:

[package.metadata.docs.rs]
rustc-args = ["--cfg", "bevy_docsrs"] # not `docsrs` because web-time fails to compile with --cfg docsrs 🤷🏼 

Also TIL that https://package.metadata.docs.rs redirects to the correct documentation page, how cool is that? ✨

[alice-i-cecile]

Great use of comments and docs here: explaining why we're doing such a weird thing is really important. Now that re-exports are working I'm happy to merge this! We'll verify this on dev-docs.bevyengine.org before shipping :)

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1672 if you'd like to help out.