Clarify vec docs on deallocation (fixes #46879)

diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 67ccb5cab6def1a8a0973466ae373ab20f8f4e0b..93d7e66b7b203b32e088581d1b02c747e93b2f6f 100644 (file)
--- a/src/liballoc/vec.rs
+++ b/src/liballoc/vec.rs
@@ -224,8 +224,10 @@
 /// types inside a `Vec`, it will not allocate space for them. *Note that in this case
 /// the `Vec` may not report a [`capacity`] of 0*. `Vec` will allocate if and only
 /// if [`mem::size_of::<T>`]`() * capacity() > 0`. In general, `Vec`'s allocation
-/// details are subtle enough that it is strongly recommended that you only
-/// free memory allocated by a `Vec` by creating a new `Vec` and dropping it.
+/// details are very subtle &mdash; if you intend to allocate memory using a `Vec`
+/// and use it for something else (either to pass to unsafe code, or to build your
+/// own memory-backed collection), be sure to deallocate this memory by using
+/// `from_raw_parts` to recover the `Vec` and then dropping it.
 ///
 /// If a `Vec` *has* allocated memory, then the memory it points to is on the heap
 /// (as defined by the allocator Rust is configured to use by default), and its