Improve docs for slice::from_raw_parts

diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index 63f9a8097ba3aace3759b902549b3f4230fee375..bfab7a4cddac56de14a5b463b7ff3ac341358f8f 100644 (file)
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -3873,9 +3873,11 @@ fn may_have_side_effect() -> bool { false }
 /// valid for `len` elements, nor whether the lifetime inferred is a suitable
 /// lifetime for the returned slice.
 ///
-/// `p` must be non-null and aligned, even for zero-length slices, as is
-/// required for all references. However, for zero-length slices, `p` can be
-/// a bogus non-dereferencable pointer such as [`NonNull::dangling()`].
+/// `data` must be non-null and aligned, even for zero-length slices. The
+/// reason for this is that enum layout optimizations may rely on references
+/// (including slices of any length) being aligned and non-null to distinguish
+/// them from other data. You can obtain a pointer that is usable as `data`
+/// for zero-length slices using [`NonNull::dangling()`].
 ///
 /// # Caveat
 ///
@@ -3910,8 +3912,8 @@ pub unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
 ///
 /// This function is unsafe for the same reasons as `from_raw_parts`, as well
 /// as not being able to provide a non-aliasing guarantee of the returned
-/// mutable slice. `p` must be non-null and aligned even for zero-length slices as with
-/// `from_raw_parts`.
+/// mutable slice. `data` must be non-null and aligned even for zero-length
+/// slices as with `from_raw_parts`.
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {