rust-lang / rust-lang/rust

rustdoc doesn't render non-trivial built-in `Sized` impls (and calls `Sized` impls auto trait impls)

Open
#149,467 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-synthetic-impls C-bug S-blocked T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Since #78181, we leverage our auto trait impl synthesizer to render negative impls of Sized for types that don't implement Sized. Contrary to actual auto traits, we intentionally never render any positive Sized impls, only negative ones or none at all. Most ADTs are unconditionally Sized, so it makes sense to omit these to avoid unnecessary visual clutter and to reduce page size.

Quick aside: Sized is not an auto trait, so ideally synthetic Sized impls wouldn't appear under a section titled Auto Trait Implementations but instead under one titled Built-in Trait Implementations (modulo bikeshedding).

I take issue with the fact that we don't render "non-trivial" built-in Sized impls. Why bother? Well, Sized is fundamental (so making a type Sized is a breaking change) and under which conditions the last field of a struct is Sized is technically part of the public API and should thus be accessible in rustdoc-generated docs.

If rustdoc@main doesn't render a Sized impl for certain generic types, they are either unconditionally or conditionally sized but sadly no further information is provided. Consider these examples:

  • struct Type<X: ?Sized>
    • is Type<T> Sized for all types T? holds if body is e.g., (Box<T>)
    • is Type<T> Sized iff T is Sized for all types T? holds if body is e.g., (T)
  • struct Type<X: Deref>
    • is it unconditionally sized?
    • is it Sized iff <T as Deref>::Target is Sized for all types T?
  • struct Type<X: ?Sized, Y: ?Sized>
    • which type param is responsible if any?
  • [and so on]

Potential CON: Could increase the artifact size for certain (a lot of?) crates. Rn it's unclear to me how bad the fallout would be. Needs to be investigated.

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 investigating rustdoc's auto trait impl synthesizer with the generic type examples in the issue, comparing unconditional and conditional Sized cases. Measure the potential artifact-size impact and decide how built-in implementations should be grouped. Done means rustdoc exposes non-trivial Sized conditions and no longer presents them misleadingly as auto trait implementations.

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
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.