Clarify docs for from_raw_parts

Original safety explanation for from_raw_parts was
unclear on safety for consuming a C string. This
clarifies when doing so is safe.

2 files changed, 8 insertions, 3 deletions

diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index e97c1637fd5..2272c5b7330 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -770,7 +770,10 @@ impl String {
     /// * The first `length` bytes at `buf` need to be valid UTF-8.
     ///
     /// Violating these may cause problems like corrupting the allocator's
-    /// internal data structures.
+    /// internal data structures. For example, it is normally **not** safe to
+    /// build a `String` from a pointer to a C `char` array containing UTF-8
+    /// _unless_ you are certain that array was originally allocated by the
+    /// Rust standard library's allocator.
     ///
     /// The ownership of `buf` is effectively transferred to the
     /// `String` which may then deallocate, reallocate or change the
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index 8c2f52172ee..9bf42e779c9 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -489,8 +489,10 @@ impl<T> Vec<T> {
     /// * `length` needs to be less than or equal to `capacity`.
     ///
     /// 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 with length `size_t`.
+    /// internal data structures. For example it is normally **not** safe
+    /// to build a `Vec<u8>` from a pointer to a C `char` array with length
+    /// `size_t`, doing so is only safe if the array was initially allocated by
+    /// a `Vec` or `String`.
     /// 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