Ambiguity w/ Subtyping & Variance Chapter

[kirawi]

In this chapter, it uses traits and an inheritance feature to illustrate subtyping, but this can be confusing since readers may associate subtyping with trait bounds/objects. The example is very similar to typical usage of dynamic dispatch, so I suggest changing the example to use structs instead, and explicitly describe the model as inheritance, rather than vaguely describing it as an "extension to the language".

Edit: After seeing how others are finding the same ambiguity, I will flesh out this issue to better review the chapter. Edit 2: Initial pass done. Most of this section suffers from over-explaining, ambiguous antecedents, contradictions, lack of transitions, convoluted explanations, lack of explanations, re-descriptions of previously described concepts, and much more.

[SOF3]

Either way, it is using the deprecated syntax of Trait instead of dyn Trait, which is confusing to new users.

[kirawi]

Maybe the best thing to do is state this is just Rust-like pseudocode with inheritance. That could eliminate a lot of ambiguity too. Though I also agree with your criticism.

Personally, I feel that the bigger change that needs to happen is that the section needs to make fewer assumptions about the reader's level of knowledge. Of course, there are also many other problems with the language itself, but they also lead to the same overall problem where it's unclear to the reader as to what the text is trying to convey. For example, I think that the Animal/Cat/Dog example in the beginning is a good introduction for people who are familiar with OOP (it's one of the most common examples that people use to explain inheritance), but I think that it should only remain in that part because inheritance does not exist in Rust, and thus will likely be unfamiliar to a large portion of the audience that don't program in an OOP language. Additionally, the example outlives its purpose once the rules for subtyping are derived from it.

A new example should be introduced when it starts talking about lifetimes. At this point, we should be talking purely about Rust, not pseudocode; the rules discussed here are specific to Rust.

Variance also needs an example of its own that will be used throughout the rest of the section instead of the Animal/Cat/Dog example. Aside from the aforementioned reasons, I don't expect the reader to be able to remember the example very well by this point.

These are some of the overall points, but there's definitely a lot more to discuss when it comes to how the section is written. I don't know when I'll have the time to do it, but it's incredibly important that it gets done eventually (whether by me or someone else). I'll happily pass the notes from my first pass if anyone wants to take a stab at it, but right now I am still intending to do my second pass.

[qsantos]

The chapter has been fully rewritten by https://github.com/rust-lang/nomicon/pull/340 following the similar remarks in https://github.com/rust-lang/nomicon/issues/339. Are there still standing points in this issue?

[kirawi]

No, and I think that additionally watching Jon Gjengset's video on this topic helps a lot. Actually, if any maintainers do read this, I also want to apologize for my tone in the original comment.

[qsantos]

Thanks for the prompt answer @kirawi. Is it possible for you to close this issue? It might help make it simpler for other people to navigate the issues.

[qsantos]

Thanks @kirawi!