Consider using fake_variadic to improve docs

[janhohenheim]

How can Bevy's documentation be improved?

fake_variadic allows docs on docs.rs to pretend they use variadics to hide tuple implementation spam.
It requires #![cfg_attr(docsrs, feature(doc_cfg, rustdoc_internals))] on lib.rs.

This is an secret, undocumented internal feature for the standard library, as far as I know. Buuuuuut there is a precedent of popular crates using it... namely serde!

See https://docs.rs/serde/latest/src/serde/de/impls.rs.html#1480-1509 for a usage example and https://docs.rs/serde/latest/serde/trait.Deserialize.html#impl-Deserialize%3C'de%3E-for-(T,) for how it is rendered:

The exact usage is:

• Use the following annotation for the first impl:

#[cfg_attr(docsrs, doc(fake_variadic))]
#[cfg_attr(
    docsrs,
    doc = "This trait is implemented for tuples up to 16 items long."
)]

• use #[cfg_attr(docsrs, doc(hidden))] on the other impls

[alice-i-cecile]

I love it we should do this.

[bash]

I'd be interested in working on this :)

Would adding an option to the all_tuples! macro be an acceptable solution?
Usage would look something like this:

all_tuples!(#[doc(fake_variadic)] impl_plugins_tuples, 0, 15, P, S);

Is bevy_utils intended for third-party use? If not then I could just do the fake variadic stuff unconditionally.

[alice-i-cecile]

IMO we should just do this unconditionally there :)

[bash]

Ah dang it. #[doc(fake_variadic)] only works on actual tuples and fn pointers.

For example this:

pub trait Example {}

macro_rules! impl_example {
    (($P:ident, $p:ident)) => {
        #[cfg_attr(docsrs, doc(fake_variadic))]
        #[cfg_attr(docsrs, doc = "This trait is implemented for tuples up to 16 items long.")]
        impl<P> Example for std::marker::PhantomData<(P,)> {}
    };
    ($(($P:ident, $p:ident)),*) => {
        #[cfg_attr(docsrs, doc(hidden))]
        impl<$($P,)*> Example for std::marker::PhantomData<($($P,)*)> {}
    };
}

bevy_utils::all_tuples!(impl_example, 0, 16, P, p);

fails with:

error: `#[doc(fake_variadic)]` must be used on the first of a set of tuple or fn pointer trait impls with varying arity

I guess this busts my dream of putting this in all_tuples! directly

[cart]

I guess this busts my dream of putting this in all_tuples! directly

Could you add an additional parameter to it that adds it in an opt-in way?