-
-
Notifications
You must be signed in to change notification settings - Fork 4.5k
Consider using fake_variadic to improve docs #14697
Copy link
Copy link
Closed
Labels
A-Cross-CuttingImpacts the entire engineImpacts the entire engineC-DocsAn addition or correction to our documentationAn addition or correction to our documentationD-StraightforwardSimple bug fixes and API improvements, docs, test and examplesSimple bug fixes and API improvements, docs, test and examplesS-Ready-For-ImplementationThis issue is ready for an implementation PR. Go for it!This issue is ready for an implementation PR. Go for it!X-ContentiousThere are nontrivial implications that should be thought throughThere are nontrivial implications that should be thought through
Milestone
Description
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
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
A-Cross-CuttingImpacts the entire engineImpacts the entire engineC-DocsAn addition or correction to our documentationAn addition or correction to our documentationD-StraightforwardSimple bug fixes and API improvements, docs, test and examplesSimple bug fixes and API improvements, docs, test and examplesS-Ready-For-ImplementationThis issue is ready for an implementation PR. Go for it!This issue is ready for an implementation PR. Go for it!X-ContentiousThere are nontrivial implications that should be thought throughThere are nontrivial implications that should be thought through