Tracking Issue for doc_label_trait

[ThierryBerger]

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)¹
• 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: https://docs.rs/bevy_docs_extension_demo/latest/bevy_docs_extension_demo/struct.TestAllTraits.html.
  • 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 Resource is also a Component, but a user isn't usually interested in knowing that it's a Component)
  • In hindsight, it's probably a bad idea to assume user is not interested in details, so I suggest to let this go.
  • See: Update trait tags for resources-as-components bevyengine/bevy#24222.
• Trait sections: module pages group items by trait role instead of one flat list. See Trait-based sections on docs.rs bevyengine/bevy#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

• Trait tag for Message bevyengine/bevy#21462

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?
  • 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.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[Aniketiitk21]

I am interested in contributing here and I want to coordinate before opening code. For a first scoped PR, I would like to implement only the first checklist item: support #[doc(label_trait)] on a type dedicated page in rustdoc, without label_trait_color or the smaller badges elsewhere yet. If that is a good first slice, I can keep the PR narrowly focused on that behavior and the corresponding tests. If you would prefer a different first step or a different place for coordination, please let me know.

[SpecificProtagonist]

Shouldn't we reuse notable_trait?

I don't see why not? The goal is the same, it's just two complimentary ways of conveying that information, depending on where you're looking.

Also, regarding the icons: I think they're gonna be more controversial, and I'm not sure they should be treated as more accepted as the restructuring of module headings based on traits you mention on your blog. Note that in Bevy, they're currently not used either.

[ThierryBerger]

• @Aniketiitk21 I started working on that on Rustdoc label trait feature #157058 ; reviews are appreciated, but I'd rather keep working on this for now.