Improve MaybeUninit::get_{ref,mut} documentation

[danielhenrymantilla]

As mentioned in #63568 (comment), MaybeUninit's get_{ref,mut} documentation is lacking, so this PR attempts to fix that.

That being said, and as @RalfJung mentions in that thread,

In particular, we should clarify that all the UB rules for these methods equally apply when calling the raw ptr methods and creating a reference manually.

these other docs also need to be improved, which I can do in this PR (hence the [WIP]).

Finally, since all these documentations are related to clearly establishing when dealing with uninitialized memory which patterns are known to be sound and which patterns are currently UB (that is, until, if ever, the rules around references to unintialized integers get relaxed, this documentation will treat them as UB, and advise against such patterns (e.g., it is not possible to use uninitialized buffers with the Read API)), I think that adding even more examples to the main documentation of MaybeUninit inherent definition wouldn't hurt either.

---

• Rendered

[rust-highfive]

r? @KodrAus

(rust_highfive has picked a reviewer for you, use r? to override)

[danielhenrymantilla]

r? @RalfJung cc @SimonSapin @Centril

[RalfJung]

Great work! These are very good examples. I just found some nits.

@Centril do you also want to take a look?

[Centril]

@RalfJung Thanks for the ping. I trust your review. :)

[danielhenrymantilla]

Okay, I have fixed "the nits", so I think that regarding get_ref and get_mut documentation, we should be good. Should we take advantage of this PR and potentially enhance the main struct's documentation as well as .as_ptr() / .as_mut_ptr()'s ?

[RalfJung]

Should we take advantage of this PR and potentially enhance the main struct's documentation as well as .as_ptr() / .as_mut_ptr()'s ?

I prefer smaller PRs, that's much easier to review.

@bors delegate+

r=me with the last nit fixed (this means you can do bors r=RalfJung then)

[bors]

✌️ @danielhenrymantilla can now approve this pull request

[danielhenrymantilla]

@bors r=RalfJung

[bors]

📌 Commit 67f2200 has been approved by RalfJung

[pr2502]

I'm sorry if this is inappropriate time or place to write this, but this is such a minor thing I hope it's better than filing an issue?

The code snippet in get_mut() documentation is incorrectly asserting the array being sorted:

assert!(
    buf.chunks(2).all(|chunk| chunk[0] <= chunk[1]),
    "buffer is sorted",
);

It should use the slice::windows method instead of slice::chunks to actually check if all elements are sorted, this test would let an array like [3, 4, 1, 2] pass as sorted.