Sharp jump in difficulty of the subtyping chapter
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 2.3k
- Forks
- 325
- PR merge metrics
- No merged PRs in 30d
Description
In https://doc.rust-lang.org/nightly/nomicon/subtyping.html:
The beginning of the chapter, up to "Variance", is easy to follow. Cat extends Animal, lifetimes are bigger or smaller = easy.
But then the language suddenly changes to purely abstract academic terminology like "type constructor in Rust is any generic type with unbound arguments", and you've lost me. When you say "constructors in Rust", I think of pub fn new() -> Self and that Vec::new() has an generic argument… but that doesn't explain variance to me at all.
The variance section switches to using F<Sub> and F<Super> instead of continuing the analogy of Cat and Animal. This makes it harder to understand, because you've just explained to me relationship based on cats and dogs, so now I wonder "is F<Sub> the Cat?"
Note about contravariance mentions "higher rank lifetimes" without any prior introduction to what "higher rank" is, how lifetimes have a "rank", etc.
The section later comes back to cats and dogs example, but at this point I'm completely confused and exhausted.
I think it'd help to fully explain variance based on cats and dogs before explaining variance in academic terms.
Contributor guide
No contributing guide indexed for this repository
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 with the subtyping.html chapter, especially the sections after "Variance," and compare their terminology with the earlier Cat and Animal explanation. Clarify variance using that analogy before introducing type constructors, F/F, and higher-rank lifetimes. Done means the chapter provides the missing concepts and a consistent path from the introductory example to the formal explanation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100