Documenting satisfying trait bounds and candidate preference

[lcnr]

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.

[ehuss]

These all look like great things!

Just FYI, we are planning on moving the Generics chapter underneath the Types chapter. Additionally, we are planning to add "Generic Arguments" to the Generics chapter, which are currently mostly missing (but lightly touched on in the Paths chapter). I don't think that should disrupt you too much, but just so you are aware.

I'm trying to relate this list to how these items might fit in the existing structure. It could be helpful to show the outline in terms of how it fits in and the planned scope. So for example:

• Types
  • Generics
    • instantiating generic parameters of an item (new section)
  • Alias types (new chapter)
  • Trait and lifetime bounds
    • satisfaction (new section)

…etc.

And just to repeat what you said to make sure I understand: It can be challenging to split it into smaller pieces because there are cyclical dependencies like equality → normalization → satisfying trait bounds → equality. Is that right?

I understand it can be difficult to sketch out the whole picture before you start building. It's expected that as you start writing the shape will become more apparent to you, and things might need to shift around as you discover how to present it.

Whenever it's possible to split things into smaller PRs, that's preferable. I understand that isn't always easy. It's OK to leave placeholders to help break the work up into smaller pieces. For example, if you need to talk about "inference variables", but that by itself could be a meaty topic, then leaving a note that it is incomplete is fine (for example, see https://doc.rust-lang.org/1.90.0/reference/names/name-resolution.html where we needed to talk about name resolution, but haven't finished describing the actual process).

I think overall what you are proposing looks great!