rust-lang / rust-lang/nomicon

Sharp jump in difficulty of the subtyping chapter

Open
#124 1 comment 2 reactions 0 assignees View on GitHub

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

  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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.