Rollup merge of rust-lang#129652 - RalfJung:ptr-to-ref, r=traviscross

fix Pointer to reference conversion docs

The aliasing rules documented in rust-lang#128157 are wrong, this fixes them.

Author: matthiaskrgr

core/src/ptr/mod.rs

@@ -57,50 +57,42 @@
 //! [`NonNull::dangling`] in such cases.
 //!
 //! ## Pointer to reference conversion
-//! When converting a pointer to a reference `&T` using `&*`,
+//!
+//! When converting a pointer to a reference (e.g. via `&*ptr` or `&mut *ptr`),
 //! there are several rules that must be followed:
 //!
 //! * The pointer must be properly aligned.
 //!
-// some microprocessors may use address 0 for an interrupt vector.
-// users of these microprocessors must always read/write address 0 through
-// a raw pointer, not a reference.
 //! * It must be non-null.
 //!
 //! * It must be "dereferenceable" in the sense defined above.
 //!
-//! * The pointer must point to a valid value of type `T`.
-//!   This means that the created reference can only refer to
-//!   uninitialized memory through careful use of `MaybeUninit`,
-//!   or if the uninitialized memory is entirely contained within
-//!   padding bytes, since
-//!   [padding has the same validity invariant as `MaybeUninit`][ucg-pad].
-//!
-//! * You must enforce Rust's aliasing rules, since the lifetime of the
-//!   created reference is arbitrarily chosen,
-//!   and does not necessarily reflect the actual lifetime of the data.
-//!   In particular, while this reference exists,
-//!   the memory the pointer points to must
-//!   not get accessed (read or written) through any raw pointer,
-//!   except for data inside an `UnsafeCell`.
-//!   Note that aliased writes are always UB for mutable references,
-//!   even if they only modify `UnsafeCell` data.
+//! * The pointer must point to a [valid value] of type `T`.
+//!
+//! * You must enforce Rust's aliasing rules. The exact aliasing rules are not decided yet, so we
+//!   only give a rough overview here. The rules also depend on whether a mutable or a shared
+//!   reference is being created.
+//!   * When creating a mutable reference, then while this reference exists, the memory it points to
+//!     must not get accessed (read or written) through any other pointer or reference not derived
+//!     from this reference.
+//!   * When creating a shared reference, then while this reference exists, the memory it points to
+//!     must not get mutated (except inside `UnsafeCell`).
 //!
 //! If a pointer follows all of these rules, it is said to be
-//! *convertible to a reference*.
+//! *convertible to a (mutable or shared) reference*.
 // ^ we use this term instead of saying that the produced reference must
 // be valid, as the validity of a reference is easily confused for the
 // validity of the thing it refers to, and while the two concepts are
 // closly related, they are not identical.
 //!
-//! These apply even if the result is unused!
+//! These rules apply even if the result is unused!
 //! (The part about being initialized is not yet fully decided, but until
 //! it is, the only safe approach is to ensure that they are indeed initialized.)
 //!
 //! An example of the implications of the above rules is that an expression such
 //! as `unsafe { &*(0 as *const u8) }` is Immediate Undefined Behavior.
 //!
-//! [ucgpad]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#padding
+//! [valid value]: ../../reference/behavior-considered-undefined.html#invalid-values
 //!
 //! ## Allocated object
 //!