rust-lang / rust-lang/rust

rustdoc-json: Show implied outlives-bounds

Open
#142,226 9 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-implied-bounds A-lifetimes A-rustdoc-json C-feature-request T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Implied bounds are a serious and underappreciated SemVer hazard:

  • They are public API, but not obvious nor written down explicitly in the location where they are public API.
  • They are "infectious", behaving similarly to auto-traits, and therefore able to cause a "spooky action at a distance" style of breakage.

Consider the following example:

pub fn example<'a, T>(value: Wrapper<'a, T>) {}

pub struct Wrapper<'a, T>(Inner<'a, T>);

struct Inner<'a, T>(&'a i64, T);

impl<'a, T> Wrapper<'a, T> { ... }

impl<'a, T> Inner<'a, T> { ... }

Noting that Inner is a private type, let's say it sees the following change:

- struct Inner<'a, T>(&'a i64, T);
+ struct Inner<'a, T: 'a>(&'a T);

The new T: 'a bound propagates in "infectious" fashion from Inner to Wrapper to example, causing breaking changes in the public API of both Wrapper and example.

Today, neither the HTML nor the JSON outputs of rustdoc show implicit bounds. Despite the breaking change, the rustdoc HTML and JSON outputs will be identical before and after this change, making it completely invisible to both consumers of the API and the maintainers who wish to not needlessly break their users.

The issue is not specific to "outlives" bounds — it also appears with T: ?Sized bounds and (I believe) any kind of trait or lifetime bound that is valid in Rust. This issue requests information on all kinds of implicit bounds.

cargo-semver-checks would like to be able to analyze changes to bounds and flag SemVer hazards. The lack of implicit bounds data means that we currently cannot do so in either direction:

  • We cannot see implicit bounds, so SemVer breakage caused by implicit bounds is invisible to us.
  • We cannot report breakage due to additions of an explicit bound, because the bound may have already been implied.
  • We cannot claim that the removal of an explicit bound in trait associated items is breaking, since (I believe) the bound may still be implied.

Exposing rustc's implicit bounds data in rustdoc JSON would resolve this problem for cargo-semver-checks. Unrelatedly, as a user of rustdoc HTML, I'd also love to see implicit bounds in HTML as well.

cc @aDotInTheVoid

@rustbot label A-rustdoc-json

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 tracing rustc's implicit-bounds data into rustdoc JSON output, using the Wrapper/Inner example as the behavioral case. Done means rustdoc JSON exposes all relevant implicit bounds so cargo-semver-checks can distinguish implied from explicit bounds; HTML exposure is an additional request.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.