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

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.

[GrigorenkoPV]

@rustbot reopen

[GrigorenkoPV]

Well, I'm powerless here. @rustbot knows how to close issues, but not how to reopen them. GitHub doesn't let me to reopen it myself. And @bors is very fond of marking issues as completed even when they aren't. #126210 addressed only one of the concerns (I've updated the OP to reflect this), but there's still a lot of work to be done.

@workingjubilee could you please help me in this and reopen the issue? Thanks!

[lolbinarycat]

whoops, yeah i should have said "part of" instead of "fixes", since my pr only addresses part of the issue, sorry about that (unfortunately i don't have the permissions to reopen issues either)