Sharp jump in difficulty of the subtyping chapter

[kornelski]

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.

[qsantos]

The chapter has been fully rewritten by https://github.com/rust-lang/nomicon/pull/340 following the remarks in https://github.com/rust-lang/nomicon/issues/339. There is no more reference to “Cat extends Animal”, which might sound intuitive, but could lead to more confusion.

At least, this avoids the back-and-forth between grounded concepts such as “Animal”, and abstract concepts such as F<Sub>.

Considering this, could this issue be closed? If there are still standing points, maybe they could be merged into #339.