Sync docs of `slice::{from_ptr_range, from_ptr_range_mut}`

1 files changed, 15 insertions, 1 deletions

diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs
index 50340a92d0d..3c5abd215a4 100644
--- a/library/core/src/slice/raw.rs
+++ b/library/core/src/slice/raw.rs
@@ -223,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:
@@ -255,6 +261,14 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
 ///
 /// 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
 ///
 /// ```