Auto merge of rust-lang#26740 - steveklabnik:gh26737, r=gankro

Fixes rust-lang#26737.

src/libcollections/string.rs

@@ -317,9 +317,14 @@ impl String {
 
     /// Creates a new `String` from a length, capacity, and pointer.
     ///
-    /// This is unsafe because:
+    /// # Unsafety
     ///
-    /// * We call `Vec::from_raw_parts` to get a `Vec<u8>`;
+    /// This is _very_ unsafe because:
+    ///
+    /// * We call `Vec::from_raw_parts` to get a `Vec<u8>`. Therefore, this
+    ///   function inherits all of its unsafety, see [its
+    ///   documentation](../vec/struct.Vec.html#method.from_raw_parts)
+    ///   for the invariants it expects, they also apply to this function.
     /// * We assume that the `Vec` contains valid UTF-8.
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/vec.rs

@@ -227,7 +227,17 @@ impl<T> Vec<T> {
 
     /// Creates a `Vec<T>` directly from the raw components of another vector.
     ///
-    /// This is highly unsafe, due to the number of invariants that aren't checked.
+    /// # Unsafety
+    ///
+    /// This is highly unsafe, due to the number of invariants that aren't
+    /// checked:
+    ///
+    /// * `ptr` needs to have been previously allocated via `String`/`Vec<T>`
+    ///   (at least, it's highly likely to be incorrect if it wasn't).
+    /// * `capacity` needs to be the capacity that the pointer was allocated with.
+    ///
+    /// Violating these may cause problems like corrupting the allocator's
+    /// internal datastructures.
     ///
     /// # Examples
     ///