rust-lang / rust-lang/reference

Documenting satisfying trait bounds and candidate preference

Open
#2,070 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

My goal is to document the changes from #120752.

This requires a lot of interdependent concepts, so it's currently a fairly big change. How do you want me to proceed here? Concretely, I would like to get input on the general structure here before discussing the specifics of this doc.

The things in bold are what I am am adding/have to add to document things. What does this rely on:

  • items
    • instantiating generic parameters of an item
  • types
    • alias types (associated types + opaque types)
      • normalizing associated types
      • the concept of a rigid alias
    • inference variables
    • placeholders
  • type equality
    • structural except for alias types, what does structural mean, concept of a rigid type
    • relating aliases
    • higher ranked
  • trait bounds
    • satisfaction: how to prove/satisfy trait bounds
      • via trait implementations
      • via in-scope where-bound
      • via item bounds of rigid aliases
      • candidate preference (what I originally set out to document)

Ways in which these things are interdependent:

  • equality of alias types needs to know about normalization
  • normalization needs to know about "satisfying trait bounds" as its behavior only makes sense in reference to that
  • satisfying trait bounds needs to talk about equality
  • using item bounds relies on the concept of rigid aliases

Additional dependencies and annoyances:

  • to explain how we use impls to satisfy a trait bound, I currently rely on inference variables and the concept of "instantiating generic parameters when using an item"
  • to explain equality and subtyping of higher ranked types, I am talking about inference variables and placeholders

I don't mind splitting this up into smaller changes and keeping things either as TODO or just not documenting things, e.g. we could just never explain what it means to "equate a type" until that gets merged separately or ignore satisfying trait bounds via item bounds of rigid aliases.

What I would like to know is:

  • does this structure seem good? Working on the concrete docs feels unpleasant while that's still up in the air
  • how do I take this structure and actually get it into the reference?

A WIP branch is in https://github.com/rust-lang/project-goal-reference-expansion/pull/7/files. Started a zulip convo for this.

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 reviewing the WIP branch in project-goal-reference-expansion PR #7 and the linked Zulip discussion about the trait solver and trait bounds. Agree on the documentation structure and whether to split the concepts into smaller changes; done means the structure is settled and the relevant material is added to the Rust Reference.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.