doc: explain why it is unsafe to construct Vec<u8> from Vec<u16>

Co-authored-by: Steve Klabnik <steve@steveklabnik.com>

1 files changed, 5 insertions, 1 deletions

diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 641f9eafa8d..5e733fa43d7 100644
--- a/src/liballoc/vec.rs
+++ b/src/liballoc/vec.rs
@@ -411,7 +411,11 @@ impl<T> Vec<T> {
     ///
     /// Violating these may cause problems like corrupting the allocator's
     /// internal data structures. For example it is **not** safe
-    /// to build a `Vec<u8>` from a pointer to a C `char` array and a `size_t`.
+    /// to build a `Vec<u8>` from a pointer to a C `char` array with length `size_t`.
+    /// It's also not safe to build one from a `Vec<u16>` and its length, because
+    /// the allocator cares about the alignment, and these two types have different
+    /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after
+    /// turning it into a `Vec<u8>` it'll be deallocated with alignment 1.
     ///
     /// The ownership of `ptr` is effectively transferred to the
     /// `Vec<T>` which may then deallocate, reallocate or change the