rust-lang / rust-lang/reference
Documenting satisfying trait bounds and candidate preference
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
- alias types (associated types + opaque types)
- 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)
- satisfaction: how to prove/satisfy trait bounds
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
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 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