Tracking Issue for doc_label_trait
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Feature gate: #![feature(doc_label_trait)]
This is a tracking issue for allowing users to mark arbitrary traits to be displayed more prominently in rustdoc.
Prototype: https://docs.rs/bevy_docs_extension_demo.
Public API
pub struct Magic;
#[doc(label_trait)]
#[doc(label_trait_color="#ff0000")]
pub trait ImportantTrait {}
impl ImportantTrait for Magic {}
Steps / History
(Remember to update the S-tracking-* label when checking boxes.)
- Add #[doc(label_trait)]: Display the labeled badge on a struct's dedicated page in rustdoc
- Add #[doc(label_trait_color="#ff0000")]
- Add a smaller colored badge next to items where relevant.
- Final comment period (FCP)^1
- Stabilization PR
More context
From https://thierryberger.com/blog/rustdoc-notable-trait/.
offline copy in case above link goes dead.
Trait-heavy framework APIs (Bevy, but also Diesel, axum, embedded HALs) have poor discoverability in default rustdoc. From a type page it is hard to answer: is this a Component? a Resource?
Trait impls are listed flatly, far from the type's header, and conceptual grouping of items by trait role does not exist.
Bevy has been experimenting with augmenting rustdoc output to surface these concepts. Let's see what you think!
Our approach today
- Trait tags: badges associated to a type indicating which Bevy traits it implements (
Component,Resource,Asset...).- Color coded, so it's better to navigate and understand at a glance.
- See them on a type's page.
- See an indication of those when referenced elsewhere
- See: https://docs.rs/bevy_docs_extension_demo/latest/bevy_docs_extension_demo/index.html#structs.
- adding emoji is fancy but a simple circle with its color coded would be enough.
Controversial
- To avoid clutter we filter them out depending on combinations (a
Resourceis also aComponent, but a user isn't usually interested in knowing that it's aComponent)- In hindsight, it's probably a bad idea to assume user is not interested in details, so I suggest to let this go.
- See: https://github.com/bevyengine/bevy/pull/24222.
- Trait sections: module pages group items by trait role instead of one flat list. See https://github.com/bevyengine/bevy/pull/17821.
- But then, if a type implements multiple "tags", where do we put it ?
How it's implemented
The current implementation is JavaScript shipped from the crate that mutates rustdoc's generated DOM at load time. It works, but:
- It depends on rustdoc's HTML/CSS structure, which is not a stable interface.
- Shipping JS from a crate to alter rustdoc output is... controversial, and will™️ be forbidden in the future.
Additional context
Maintenance of the JS approach
Abandoned ideas
Require<C>marker trait: abusing trait markers to "tag" components, too noisy.- required components section via the wrapper: rustdoc wrapper was rejected.
Unresolved Questions
- Which API exactly should be implemented ? Maybe the
doc(label_trait_color = "#ff0000")is enough to infer its existence.doc(label_trait(color="#ff0000"))]
- How should the color be written (hex...?)
- Hex 👌
- Should rust-analyzer hop on that feature to also display those traits? (notable_traits display them on hover of an type implementing that trait)
- Shouldn't we reuse
notable_trait: https://github.com/rust-lang/rust/issues/45040?- Reading notable_trait feature really makes it feel similar:
Rustdoc keeps a list of a few traits that are believed to be "fundamental" to types that implement them.
- Reading notable_trait feature really makes it feel similar:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the doc_label_trait feature gate, the public API example, and the linked prototype to understand the intended rustdoc output. Review the tracking checklist and unresolved questions, especially interaction with notable_trait; completion requires resolving the design and implementation steps before FCP and stabilization.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- compilers, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100