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

Fixes rust-lang#26737.

Author: bors

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
  ///