Improve #Safety of various methods in core::ptr

src/libcore/ptr/mod.rs

@@ -119,10 +119,13 @@ mod mut_ptr;
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `to_drop` must be [valid] for reads.
+/// * `to_drop` must be [valid] for both reads and writes.
 ///
 /// * `to_drop` must be properly aligned.
 ///
+/// * The value `to_drop` points to must be valid for dropping, which may mean it must uphold
+///   additional invariants - this is type-dependent.
+///
 /// Additionally, if `T` is not [`Copy`], using the pointed-to value after
 /// calling `drop_in_place` can cause undefined behavior. Note that `*to_drop =
 /// foo` counts as a use because it will cause the value to be dropped
@@ -289,7 +292,7 @@ pub const fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T] {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * Both `x` and `y` must be [valid] for reads and writes.
+/// * Both `x` and `y` must be [valid] for both reads and writes.
 ///
 /// * Both `x` and `y` must be properly aligned.
 ///
@@ -355,7 +358,7 @@ pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * Both `x` and `y` must be [valid] for reads and writes of `count *
+/// * Both `x` and `y` must be [valid] for both reads and writes of `count *
 ///   size_of::<T>()` bytes.
 ///
 /// * Both `x` and `y` must be properly aligned.
@@ -471,10 +474,12 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `dst` must be [valid] for writes.
+/// * `dst` must be [valid] for both reads and writes.
 ///
 /// * `dst` must be properly aligned.
 ///
+/// * `dst` must point to a properly initialized value of type `T`.
+///
 /// Note that even if `T` has size `0`, the pointer must be non-NULL and properly aligned.
 ///
 /// [valid]: ../ptr/index.html#safety
@@ -514,6 +519,8 @@ pub unsafe fn replace<T>(dst: *mut T, mut src: T) -> T {
 /// * `src` must be properly aligned. Use [`read_unaligned`] if this is not the
 ///   case.
 ///
+/// * `src` must point to a properly initialized value of type `T`.
+///
 /// Note that even if `T` has size `0`, the pointer must be non-NULL and properly aligned.
 ///
 /// # Examples
@@ -628,6 +635,8 @@ pub unsafe fn read<T>(src: *const T) -> T {
 ///
 /// * `src` must be [valid] for reads.
 ///
+/// * `src` must point to a properly initialized value of type `T`.
+///
 /// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of
 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
 /// value and the value at `*src` can [violate memory safety][read-ownership].
@@ -922,6 +931,8 @@ pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 ///
 /// * `src` must be properly aligned.
 ///
+/// * `src` must point to a properly initialized value of type `T`.
+///
 /// Like [`read`], `read_volatile` creates a bitwise copy of `T`, regardless of
 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
 /// value and the value at `*src` can [violate memory safety][read-ownership].