///
/// # Panics
///
- /// Panics if the new capacity overflows `usize`.
+ /// Panics if the new capacity exceeds `isize::MAX` bytes.
///
/// # Examples
///
///
/// # Panics
///
- /// Panics if the number of elements in the vector overflows a `usize`.
+ /// Panics if the new capacity exceeds `isize::MAX` bytes.
///
/// # Examples
///
/// Creates a draining iterator that removes the specified range in the vector
/// and yields the removed items.
///
- /// Note 1: The element range is removed even if the iterator is only
- /// partially consumed or not consumed at all.
- ///
- /// Note 2: It is unspecified how many elements are removed from the vector
- /// if the `Drain` value is leaked.
+ /// When the iterator **is** dropped, all elements in the range are removed
+ /// from the vector, even if the iterator was not fully consumed. If the
+ /// iterator **is not** dropped (with [`mem::forget`] for example), it is
+ /// unspecified how many elements are removed.
///
/// # Panics
///