apply comments

src/libcore/intrinsics.rs

@@ -1024,10 +1024,9 @@ extern "rust-intrinsic" {
     ///         // not alias, and two different vectors cannot own the same
     ///         // memory.
     ///         ptr::copy_nonoverlapping(src, dst, src_len);
-    ///     }
     ///
-    ///     unsafe {
-    ///         // Truncate `src` without dropping its contents.
+    ///         // Truncate `src` without dropping its contents. This cannot panic,
+    ///         // so double-drops cannot happen.
     ///         src.set_len(0);
     ///
     ///         // Notify `dst` that it now holds the contents of `src`.
@@ -1054,7 +1053,9 @@ extern "rust-intrinsic" {
     /// If the source and destination will *never* overlap,
     /// [`copy_nonoverlapping`] can be used instead.
     ///
-    /// `copy` is semantically equivalent to C's [`memmove`].
+    /// `copy` is semantically equivalent to C's [`memmove`].  Copying takes place as
+    /// if the bytes were copied from `src` to a temporary array and then copied from
+    /// the array to `dst`-
     ///
     /// [`copy_nonoverlapping`]: ./fn.copy_nonoverlapping.html
     /// [`memmove`]: https://www.gnu.org/software/libc/manual/html_node/Copying-Strings-and-Arrays.html#index-memmove
@@ -1143,7 +1144,7 @@ extern "rust-intrinsic" {
     ///
     /// Creating an invalid value:
     ///
-    /// ```no_run
+    /// ```
     /// use std::ptr;
     ///
     /// let mut v = Box::new(0i32);
@@ -1155,7 +1156,10 @@ extern "rust-intrinsic" {
     /// }
     ///
     /// // At this point, using or dropping `v` results in undefined behavior.
-    /// // v = Box::new(0i32); // ERROR
+    /// // drop(v); // ERROR
+    ///
+    /// // Leaking it does not invoke drop and is fine:
+    /// mem::forget(v)
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn write_bytes<T>(dst: *mut T, val: u8, count: usize);

src/libcore/ptr.rs

@@ -274,7 +274,8 @@ pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
 ///   size_of::<T>()` bytes must *not* overlap with the region of memory
 ///   beginning at `y` with the same size.
 ///
-/// Note that even if `T` has size `0`, the pointers must be non-NULL and properly aligned.
+/// Note that even if the effectively copied size (`count * size_of::<T>()`) is `0`,
+/// the pointers must be non-NULL and properly aligned.
 ///
 /// [valid]: ../ptr/index.html#safety
 ///
@@ -369,7 +370,7 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
     }
 }
 
-/// Moves `src` into the pointed `dest`, returning the previous `dest` value.
+/// Moves `src` into the pointed `dst`, returning the previous `dst` value.
 ///
 /// Neither value is dropped.
 ///
@@ -383,9 +384,9 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
 ///
 /// Behavior is undefined if any of the following conditions are violated:
 ///
-/// * `dest` must be [valid] for writes.
+/// * `dst` must be [valid] for writes.
 ///
-/// * `dest` must be properly aligned.
+/// * `dst` must be properly aligned.
 ///
 /// Note that even if `T` has size `0`, the pointer must be non-NULL and properly aligned.
 ///
@@ -409,8 +410,8 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
 /// ```
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
-pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
-    mem::swap(&mut *dest, &mut src); // cannot overlap
+pub unsafe fn replace<T>(dst: *mut T, mut src: T) -> T {
+    mem::swap(&mut *dst, &mut src); // cannot overlap
     src
 }
 
@@ -447,8 +448,8 @@ pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
 ///
 /// let mut s = String::from("foo");
 /// unsafe {
-///     // `s2` now points to the same underlying memory as `s1`.
-///     let mut s2 = ptr::read(&s);
+///     // `s2` now points to the same underlying memory as `s`.
+///     let mut s2: String = ptr::read(&s);
 ///
 ///     assert_eq!(s2, "foo");
 ///
@@ -558,7 +559,6 @@ pub unsafe fn read<T>(src: *const T) -> T {
 /// use std::ptr;
 ///
 /// #[repr(packed, C)]
-/// #[derive(Default)]
 /// struct Packed {
 ///     _padding: u8,
 ///     unaligned: u32,
@@ -570,10 +570,11 @@ pub unsafe fn read<T>(src: *const T) -> T {
 /// };
 ///
 /// let v = unsafe {
-///     // Take a reference to a 32-bit integer which is not aligned.
-///     let unaligned = &x.unaligned;
+///     // Take the address of a 32-bit integer which is not aligned.
+///     // This must be done as a raw pointer; unaligned references are invalid.
+///     let unaligned = &x.unaligned as *const u32;
 ///
-///     // Dereferencing normally will emit an unaligned load instruction,
+///     // Dereferencing normally will emit an aligned load instruction,
 ///     // causing undefined behavior.
 ///     // let v = *unaligned; // ERROR
 ///