rustdoc: Actually render the new sizedness bounds if `sized_hierarchy` is enabled unless `#![doc(dont_leak_sized_hierarchy)]` (to be used in the stdlib)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Sibling issue: https://github.com/rust-lang/rust/issues/91187.
Currently, we semi-successfully try to hide the unstable MetaSized and PointeeSized bounds in all rustdoc-generated docs because we don't want to confuse and frighten readers of the stdlib API docs which is perfectly reasonable. For example, for inlined cross-crate re-exports (IXCRE) we don't try to reconstruct PointeeSized bounds (so we essentially hide them) and we drop MetaSized bound (so we basically replace MetaSized with ?Sized) bounds. Most notably, this affects std (since it re-exports core and alloc). However, it doesn't really concern core or alloc since HIR cleaning wasn't taught these rules (likely an oversight?).
The issue with this approach is twofold:
- Users who enable
sized_hierarchyfor their own crates obviously know the feature but still rustdoc doesn't offer them a great experience - rustdoc cannot properly "handle" sized hierarchy internally
- e.g., IXCRE
PointeeSizedsupport isn't automatic, it needs dedicated code for reconstructing these bounds (which isn't hard but-) - so a hypothetical stabilization PR for SH can't just switch over to the proper rendering by just flipping a switch somewhere
- it currently contains minor hacks everywhere instead of robust well thought-out code much to the detriment of maintainability (esp. wrt. legibility & extensibility)
- e.g., IXCRE
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 by reading rustdoc's HIR cleaning and inlined cross-crate re-export (IXCRE) handling, along with sibling issue #91187. Trace how MetaSized and PointeeSized bounds are currently hidden or reconstructed, then define behavior for sized_hierarchy and doc(dont_leak_sized_hierarchy) that applies consistently to core, alloc, and std documentation.
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
- 30/100