Implement ptr_as_ref_unchecked by GrigorenkoPV · Pull Request #122492 · rust-lang/rust (original) (raw)

Oh wow, it has been 1½ months already. Sorry, got caught up with IRL shenanigans.

Anyways

Documentation

Indeed, an overhaul is needed.

What needs to be done

I would argue that the documentation pieces for

1. <*const T>::as_ref
2. <*const T>::as_ref_unchecked
3. <*mut T>::as_ref
4. <*mut T>::as_ref_unchecked
5. <*mut T>::as_mut
6. <*mut T>::as_mut_unchecked

should stay more or less in sync, so it doesn't really make sense to modify half of those without modifying the others. On top of that, it's probably not going to be a trivial fix, because there's quite a few problems to address:

• Duplication of nearly identical documentation in 3 (now to be 6) methods (not including the as_uninint_ref stuff), a glaring DRY violation.
• Wording around UnsafeCell
• Wording around the output's lifetime
• Generally subpar wording, probably due to these docs' being a patchwork of many separate changes.
• Doctests not testing anything or having hidden asserts for some reason.

This PR?

With that said, I feel like non-trivial changes to existing documentation is out of scope for a PR simply implementing some counterparts for existing APIs. Counterargument: this PR doubles the amount of flawed documentation, reaching the critical mass, so it should resolve this issue or at least be blocked on it. In any case, I don't feel like I would be able to tackle the documentation issues, so I am asking anyone else to approach this if they are willing to do so.

So, should I open a separate issue? Is this PR blocked until the issue is resolved, or can we move on in the meantime?

Const-stability

Are we sure we should be associating this with const-stability of this set of fn instead of just landing these as const stable when we land them?

Yes, I would say so. All of the as_ref/as_uninit_ref/as_uninit_slice_mut and friends are const-gated behind this feature, so I see no reason, to treat this one differently. Especially considering how similar it is to as_ref. (If I understand correctly, a method that is const-stable but not generally stable still cannot be used, even in const contexts, without a feature gate? If that is so, then I see no problem with reusing that const_ptr_as_ref). Any counterarguments?

Can you make sure the two issues are crosslinked and mention that as an option?

Well, #91822 already got notified because I mentioned it in code, but I will mention it once more right now. I am also going to ask to update the tracking issue OP when and if this PR gets merged using this feature gate.

Beep-boop

@rustbot review