Rollup merge of #142315 - lolbinarycat:core-dedup-ptr-docs-139190-pt3, r=workingjubilee

core::ptr: deduplicate docs for as_ref, addr, and as_uninit_ref

also add INFO.md file explaining the purpose of the ptr/docs dir, and give some pointers (heh) to future maintainers.

follow up to rust-lang/rust#142101

part of rust-lang/rust#139190

r? `@workingjubilee`

4 files changed, 77 insertions, 0 deletions

diff --git a/library/core/src/ptr/docs/INFO.md b/library/core/src/ptr/docs/INFO.md
new file mode 100644
index 00000000000..28a0da4926a
--- /dev/null
+++ b/library/core/src/ptr/docs/INFO.md
@@ -0,0 +1,21 @@
+This directory holds method documentation that otherwise
+would be duplicated across mutable and immutable pointers.
+
+Note that most of the docs here are not the complete docs
+for their corresponding method. This is for a few reasons:
+
+1. Examples need to be different for mutable/immutable
+   pointers, in order to actually call the correct method.
+2. Link reference definitions are frequently different
+   between mutable/immutable pointers, in order to link to
+   the correct method.
+   For example, `<*const T>::as_ref` links to
+   `<*const T>::is_null`, while `<*mut T>::as_ref` links to
+   `<*mut T>::is_null`.
+3. Many methods on mutable pointers link to an alternate
+   version that returns a mutable reference instead of
+   a shared reference.
+
+Always review the rendered docs manually when making
+changes to these files to make sure you're not accidentally
+splitting up a section.
diff --git a/library/core/src/ptr/docs/addr.md b/library/core/src/ptr/docs/addr.md
new file mode 100644
index 00000000000..785b88a9987
--- /dev/null
+++ b/library/core/src/ptr/docs/addr.md
@@ -0,0 +1,22 @@
+Gets the "address" portion of the pointer.
+
+This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of
+the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that
+casting the returned address back to a pointer yields a [pointer without
+provenance][without_provenance], which is undefined behavior to dereference. To properly
+restore the lost information and obtain a dereferenceable pointer, use
+[`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].
+
+If using those APIs is not possible because there is no way to preserve a pointer with the
+required provenance, then Strict Provenance might not be for you. Use pointer-integer casts
+or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]
+instead. However, note that this makes your code less portable and less amenable to tools
+that check for compliance with the Rust memory model.
+
+On most platforms this will produce a value with the same bytes as the original
+pointer, because all the bytes are dedicated to describing the address.
+Platforms which need to store additional information in the pointer may
+perform a change of representation to produce a value containing only the address
+portion of the pointer. What that means is up to the platform to define.
+
+This is a [Strict Provenance][crate::ptr#strict-provenance] API.
diff --git a/library/core/src/ptr/docs/as_ref.md b/library/core/src/ptr/docs/as_ref.md
new file mode 100644
index 00000000000..0c0d2768c74
--- /dev/null
+++ b/library/core/src/ptr/docs/as_ref.md
@@ -0,0 +1,19 @@
+Returns `None` if the pointer is null, or else returns a shared reference to
+the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]
+must be used instead.
+
+# Safety
+
+When calling this method, you have to ensure that *either* the pointer is null *or*
+the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
+
+# Panics during const evaluation
+
+This method will panic during const evaluation if the pointer cannot be
+determined to be null or not. See [`is_null`] for more information.
+
+# Null-unchecked version
+
+If you are sure the pointer can never be null and are looking for some kind of
+`as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can
+dereference the pointer directly.
diff --git a/library/core/src/ptr/docs/as_uninit_ref.md b/library/core/src/ptr/docs/as_uninit_ref.md
new file mode 100644
index 00000000000..5b9a1ecb85b
--- /dev/null
+++ b/library/core/src/ptr/docs/as_uninit_ref.md
@@ -0,0 +1,15 @@
+Returns `None` if the pointer is null, or else returns a shared reference to
+the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
+that the value has to be initialized.
+
+# Safety
+
+When calling this method, you have to ensure that *either* the pointer is null *or*
+the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
+Note that because the created reference is to `MaybeUninit<T>`, the
+source pointer can point to uninitialized memory.
+
+# Panics during const evaluation
+
+This method will panic during const evaluation if the pointer cannot be
+determined to be null or not. See [`is_null`] for more information.