rust-lang / rust-lang/rust

rustdoc: Actually render the new sizedness bounds if `sized_hierarchy` is enabled unless `#![doc(dont_leak_sized_hierarchy)]` (to be used in the stdlib)

Open
#157,247 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug F-sized_hierarchy T-rustdoc
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:

  1. Users who enable sized_hierarchy for their own crates obviously know the feature but still rustdoc doesn't offer them a great experience
  2. rustdoc cannot properly "handle" sized hierarchy internally
    • e.g., IXCRE PointeeSized support 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)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.