Rollup merge of #102607 - WaffleLapkin:docky_docky_slice_from_ptr_range, r=joshtriplett

Improve documentation of `slice::{from_ptr_range, from_ptr_range_mut}`

Document panic conditions (`T` is a ZST) and sync docs of shared/unique version.

cc `@wx-csy`

1 files changed, 23 insertions, 1 deletions

diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs
index f1e8bc79bf4..3c5abd215a4 100644
--- a/library/core/src/slice/raw.rs
+++ b/library/core/src/slice/raw.rs
@@ -188,6 +188,10 @@ pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
 ///
 /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
 ///
+/// # Panics
+///
+/// This function panics if `T` is a Zero-Sized Type (“ZST”).
+///
 /// # Caveat
 ///
 /// The lifetime for the returned slice is inferred from its usage. To
@@ -219,9 +223,15 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
     unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) }
 }
 
-/// Performs the same functionality as [`from_ptr_range`], except that a
+/// Forms a mutable slice from a pointer range.
+///
+/// This is the same functionality as [`from_ptr_range`], except that a
 /// mutable slice is returned.
 ///
+/// This function is useful for interacting with foreign interfaces which
+/// use two pointers to refer to a range of elements in memory, as is
+/// common in C++.
+///
 /// # Safety
 ///
 /// Behavior is undefined if any of the following conditions are violated:
@@ -247,6 +257,18 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
 ///
 /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
 ///
+/// # Panics
+///
+/// This function panics if `T` is a Zero-Sized Type (“ZST”).
+///
+/// # Caveat
+///
+/// The lifetime for the returned slice is inferred from its usage. To
+/// prevent accidental misuse, it's suggested to tie the lifetime to whichever
+/// source lifetime is safe in the context, such as by providing a helper
+/// function taking the lifetime of a host value for the slice, or by explicit
+/// annotation.
+///
 /// # Examples
 ///
 /// ```