Skip to content

Consider using fake_variadic to improve docs #14697

@janhohenheim

Description

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

image

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-Cross-CuttingImpacts the entire engineC-DocsAn addition or correction to our documentationD-StraightforwardSimple bug fixes and API improvements, docs, test and examplesS-Ready-For-ImplementationThis issue is ready for an implementation PR. Go for it!X-ContentiousThere are nontrivial implications that should be thought through

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions