Subpar documentation for ptr-to-ref conversion methods

While trying to merge #122492, some issues with the existing documentation became apparent.

The methods in question

• <*const T>::as_ref
• <*mut T>::as_ref
• <*mut T>::as_mut
• <*const T>::as_ref_unchecked [^unchecked]
• <*mut T>::as_ref_unchecked [^unchecked]
• <*mut T>::as_mut_unchecked [^unchecked]
• <*const T>::as_uninit_ref [^uninit]
• <*mut T>::as_uninit_ref [^uninit]
• <*mut T>::as_uninit_mut [^uninit]

[^unchecked]: Not yet stabilized (#122034)
[^uninit]: Not yet stabilized (#75402)

The problems

• The overarching pain-point is that big parts of documentation are repeated for all (or at least the most) of the methods, which makes it difficult to keep the wording in sync.

Documentation

• Generally subpar wording (probably due to these docs' being a patchwork of many separate changes). But also specifically:
• Imprecise wording around UnsafeCell
• Needlessly scary wording around the output's lifetime Or not?

Doctests

• Currently, they do printing instead of asserting. This should probably be changed to assertions. (Fixed in #126210)
• The assertions that we want should reflect the API being tested. (For example, we probably want an assertion that null pointer gets converted to None for as_ref, but no such assertion for as_ref_unchecked is possible.)
• Currently some asserts are hidden. Why?

Moving forward

Feel free to voice your opinions/wishes/suggestions/questions regarding this issue or to submit PRs addressing any of the problems above (not necessarily all at once). Also, doctests can probably be worked on independently from the documentation itself.

Beep-Boop

@rustbot label +A-docs +A-doctests +C-discussion +C-enhancement +E-help-wanted

And now footnotes: