Improve documentation of std::ptr::NonNull

[crlf0710]

This type used to be experimental and internal (when it was called Shared), now that it is finally being stablized (see #27730, #47631), people are complaining that the current document texts are not easy to understand.

Current text *mut T but non-zero and covariant. talks about the covariance, which is not mentioned elsewhere in the libstd docs and the Rust books. (I know it's mentioned in Nomicon but beginners seldom have read it.)

I suggest the docs be either supplemented with concrete explanations or reworked upon.

[frewsxcv]

worth mentioning that the nomicon has a section on covriance: https://doc.rust-lang.org/beta/nomicon/subtyping.html

[mjbshaw]

One question I have that I'd love to be explicitly answered:

Does NonNull<T> have the same ABI as *mut T?

The Nomicon says "If T is an FFI-safe non-nullable pointer type, Option<T> is guaranteed to have the same layout and ABI as T and is therefore also FFI-safe." This documentation and explicit statement gives some guarantees regarding Option, and it's really nice to be able to use Option in FFI code. I would love to have similar guarantees and documentation for NonNull so I could use it in some FFI-related code. But before I can use NonNull I need to make sure that I won't accidentally change my code's ABI.

[steveklabnik]

Other issues: #52978

[aticu]

The documentation of the as_ref and as_mut methods of NonNull are missing a Safety section. Presumably they require

• the same safety considerations as std::ptr::read (both) and std::ptr::write (as_mut)
• that the allocation of the value outlives the self lifetime
• that there are no aliasing references that violate the immutable XOR mutable scheme

Did I miss anything?

[RalfJung]

That sounds reasonable, I cannot think of anything else of the top of my head.

I would combine the last two points though:

• For the duration of the self lifetime, the allocation continues to exist and there are no aliasing references that violate the immutable XOR mutable scheme for the memory pointed to by the returned reference.

[Dylan-DPC]

There have been several changes to this since this issue was created, and this should satisfy this issue. There is scope for more but a newer issue would be better than this one being buried deep in the issue tracker.