Subpar documentation for ptr-to-ref conversion methods

[GrigorenkoPV]

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 ¹
• <*mut T>::as_ref_unchecked ¹
• <*mut T>::as_mut_unchecked ¹
• <*const T>::as_uninit_ref ²
• <*mut T>::as_uninit_ref ²
• <*mut T>::as_uninit_mut ²

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 docs(core): make more const_ptr doctests assert instead of printing #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:

Footnotes

1. Not yet stabilized (Tracking Issue for raw-pointer-to-reference conversion methods #122034) ↩ ↩² ↩³

2. Not yet stabilized (Tracking Issue for pointer methods returning MaybeUninit<T> #75402) ↩ ↩² ↩³

[lolbinarycat]

@rustbot claim

i'll tackle normalizing the doctests first, since the wording of the pointer methods has implications for unsafe code guidelines.