Reexplain NonNull's covariance details more concisely

[workingjubilee]

Location

std::ptr::NonNull
https://doc.rust-lang.org/stable/std/ptr/struct.NonNull.html

Summary

This page spills a lot of digital ink on the matter of covariance versus invariance. The fact of the matter is it is usually correct to use, which is why it was chosen to be like that. There are abstractions that require invariance, but they must be designed carefully to begin with, and the current format of the description is very repetitive. In practice, we have not seen an explosion of bugs from people using NonNull incorrectly over the past 60 versions, and I do not believe it is primarily because of the documented cautions. I do, however, see people incorrectly using &mut T, &T when they want NonNull<T>.

A more precise summarization would be more useful and less intimidating.

[workingjubilee]

In particular, if we want to discuss "if your type cannot safely be covariant" at all, then we should provide a very simple example of that case.

[xizheyin]

I think there also needs to be a clearer explanation here (https://doc.rust-lang.org/reference/subtyping.html#r-subtyping.variance.invariant), such as some examples, because the concepts are very difficult for newbies to understand.