Improve documentation on String's methods

Part of #29376

src/libcollections/string.rs

@@ -291,13 +291,23 @@ pub struct FromUtf8Error {
 pub struct FromUtf16Error(());
 
 impl String {
-    /// Creates a new string buffer initialized with the empty string.
+    /// Creates a new empty `String`.
+    ///
+    /// Given that the `String` is empty, this will not allocate any initial
+    /// buffer. While that means that this initial operation is very
+    /// inexpensive, but may cause excessive allocation later, when you add
+    /// data. If you have an idea of how much data the `String` will hold,
+    /// consider the [`with_capacity()`] method to prevent excessive
+    /// re-allocation.
+    ///
+    /// [`with_capacity()`]: #method.with_capacity
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
-    /// # #![allow(unused_mut)]
+    /// let s = String::new();
-    /// let mut s = String::new();
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -305,12 +315,26 @@ impl String {
         String { vec: Vec::new() }
     }
 
-    /// Creates a new string buffer with the given capacity.
+    /// Creates a new empty `String` with a particular capacity.
-    /// The string will be able to hold exactly `capacity` bytes without
+    ///
-    /// reallocating. If `capacity` is 0, the string will not allocate.
+    /// `String`s have an internal buffer to hold their data. The capacity is
+    /// the length of that buffer, and can be queried with the [`capacity()`]
+    /// method. This method creates an empty `String`, but one with an initial
+    /// buffer that can hold `capacity` bytes. This is useful when you may be
+    /// appending a bunch of data to the `String`, reducing the number of
+    /// reallocations it needs to do.
+    ///
+    /// [`capacity()`]: #method.capacity
+    ///
+    /// If the given capacity is `0`, no allocation will occur, and this method
+    /// is identical to the [`new()`] method.
+    ///
+    /// [`new()`]: #method.new
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::with_capacity(10);
     ///
@@ -346,26 +370,30 @@ impl String {
 
     /// Converts a vector of bytes to a `String`.
     ///
-    /// A string slice (`&str`) is made of bytes (`u8`), and a vector of bytes
+    /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a vector of bytes
-    /// (`Vec<u8>`) is made of bytes, so this function converts between the
+    /// ([`Vec<u8>`]) is made of bytes, so this function converts between the
     /// two. Not all byte slices are valid `String`s, however: `String`
     /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that
     /// the bytes are valid UTF-8, and then does the conversion.
     ///
+    /// [`&str`]: ../primitive.str.html
+    /// [`u8`]: ../primitive.u8.html
+    /// [`Vec<u8>`]: ../vec/struct.Vec.html
+    ///
     /// If you are sure that the byte slice is valid UTF-8, and you don't want
     /// to incur the overhead of the validity check, there is an unsafe version
-    /// of this function, [`from_utf8_unchecked()`][fromutf8], which has the
+    /// of this function, [`from_utf8_unchecked()`], which has the same behavior
-    /// same behavior but skips the check.
+    /// but skips the check.
     ///
-    /// [fromutf8]: struct.String.html#method.from_utf8_unchecked
+    /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked
     ///
     /// This method will take care to not copy the vector, for efficiency's
     /// sake.
     ///
     /// If you need a `&str` instead of a `String`, consider
-    /// [`str::from_utf8()`][str].
+    /// [`str::from_utf8()`].
     ///
-    /// [str]: ../str/fn.from_utf8.html
+    /// [`str::from_utf8()`]: ../str/fn.from_utf8.html
     ///
     /// # Failure
     ///
@@ -395,10 +423,10 @@ impl String {
     /// assert!(String::from_utf8(sparkle_heart).is_err());
     /// ```
     ///
-    /// See the docs for [`FromUtf8Error`][error] for more details on what you
+    /// See the docs for [`FromUtf8Error`] for more details on what you can do
-    /// can do with this error.
+    /// with this error.
     ///
-    /// [error]: struct.FromUtf8Error.html
+    /// [`FromUtf8Error`]: struct.FromUtf8Error.html
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error> {
@@ -415,24 +443,28 @@ impl String {
 
     /// Converts a slice of bytes to a `String`, including invalid characters.
     ///
-    /// A string slice (`&str`) is made of bytes (`u8`), and a slice of bytes
+    /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a slice of
-    /// (`&[u8]`) is made of bytes, so this function converts between the two.
+    /// bytes ([`&[u8]`]) is made of bytes, so this function converts between
-    /// Not all byte slices are valid string slices, however: `&str` requires
+    /// the two. Not all byte slices are valid string slices, however: [`&str`]
-    /// that it is valid UTF-8. During this conversion, `from_utf8_lossy()`
+    /// requires that it is valid UTF-8. During this conversion,
-    /// will replace any invalid UTF-8 sequences with
+    /// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with
     /// `U+FFFD REPLACEMENT CHARACTER`, which looks like this: <20>
     ///
+    /// [`&str`]: ../primitive.str.html
+    /// [`u8`]: ../primitive.u8.html
+    /// [`&[u8]`]: ../primitive.slice.html
+    ///
     /// If you are sure that the byte slice is valid UTF-8, and you don't want
     /// to incur the overhead of the conversion, there is an unsafe version
-    /// of this function, [`from_utf8_unchecked()`][fromutf8], which has the
+    /// of this function, [`from_utf8_unchecked()`], which has the same behavior
-    /// same behavior but skips the checks.
+    /// but skips the checks.
     ///
-    /// [fromutf8]: struct.String.html#method.from_utf8_unchecked
+    /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked
     ///
-    /// If you need a `&str` instead of a `String`, consider
+    /// If you need a [`&str`] instead of a `String`, consider
-    /// [`str::from_utf8()`][str].
+    /// [`str::from_utf8()`].
     ///
-    /// [str]: ../str/fn.from_utf8.html
+    /// [`str::from_utf8()`]: ../str/fn.from_utf8.html
     ///
     /// # Examples
     ///
@@ -576,12 +608,14 @@ impl String {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// // 𝄞music
     /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
     ///           0x0073, 0x0069, 0x0063];
-    /// assert_eq!(String::from_utf16(v).unwrap(),
+    /// assert_eq!(String::from("𝄞music"),
-    ///            "𝄞music".to_string());
+    ///            String::from_utf16(v).unwrap());
     ///
     /// // 𝄞mu<invalid>ic
     /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
@@ -598,14 +632,16 @@ impl String {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// // 𝄞mus<invalid>ic<invalid>
     /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
     ///           0x0073, 0xDD1E, 0x0069, 0x0063,
     ///           0xD834];
     ///
-    /// assert_eq!(String::from_utf16_lossy(v),
+    /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"),
-    ///            "𝄞mus\u{FFFD}ic\u{FFFD}".to_string());
+    ///            String::from_utf16_lossy(v));
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -617,13 +653,37 @@ impl String {
     ///
     /// # Safety
     ///
-    /// This is _very_ unsafe because:
+    /// This is highly unsafe, due to the number of invariants that aren't
+    /// checked:
     ///
-    /// * We call `Vec::from_raw_parts` to get a `Vec<u8>`. Therefore, this
+    /// * The memory at `ptr` needs to have been previously allocated by the
-    ///   function inherits all of its unsafety, see [its
+    ///   same allocator the standard library uses.
-    ///   documentation](../vec/struct.Vec.html#method.from_raw_parts)
+    /// * `length` needs to be less than or equal to `capacity`.
-    ///   for the invariants it expects, they also apply to this function.
+    /// * `capacity` needs to be the correct value.
-    /// * We assume that the `Vec` contains valid UTF-8.
+    ///
+    /// Violating these may cause problems like corrupting the allocator's
+    /// internal datastructures.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use std::mem;
+    ///
+    /// unsafe {
+    ///     let s = String::from("hello");
+    ///     let ptr = s.as_ptr();
+    ///     let len = s.len();
+    ///     let capacity = s.capacity();
+    ///
+    ///     mem::forget(s);
+    ///
+    ///     let s = String::from_raw_parts(ptr as *mut _, len, capacity);
+    ///
+    ///     assert_eq!(String::from("hello"), s);
+    /// }
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub unsafe fn from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String {
@@ -633,15 +693,16 @@ impl String {
     /// Converts a vector of bytes to a `String` without checking that the
     /// string contains valid UTF-8.
     ///
-    /// See the safe version, [`from_utf8()`][fromutf8], for more.
+    /// See the safe version, [`from_utf8()`], for more details.
     ///
-    /// [fromutf8]: struct.String.html#method.from_utf8
+    /// [`from_utf8()`]: struct.String.html#method.from_utf8
     ///
     /// # Safety
     ///
-    /// This function is unsafe because it does not check that the bytes passed to
+    /// This function is unsafe because it does not check that the bytes passed
-    /// it are valid UTF-8. If this constraint is violated, undefined behavior
+    /// to it are valid UTF-8. If this constraint is violated, it may cause
-    /// results, as the rest of Rust assumes that `String`s are valid UTF-8.
+    /// memory unsafety issues with future users of the `String`, as the rest of
+    /// the standard library assumes that `String`s are valid UTF-8.
     ///
     /// # Examples
     ///
@@ -663,14 +724,19 @@ impl String {
         String { vec: bytes }
     }
 
-    /// Returns the underlying byte buffer, encoded as UTF-8.
+    /// Converts a `String` into a byte vector.
+    ///
+    /// This consumes the `String`, so we do not need to copy its contents.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let s = String::from("hello");
     /// let bytes = s.into_bytes();
-    /// assert_eq!(bytes, [104, 101, 108, 108, 111]);
+    ///
+    /// assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -687,14 +753,18 @@ impl String {
         self
     }
 
-    /// Pushes the given string onto this string buffer.
+    /// Appends a given string slice onto the end of this `String`.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("foo");
+    ///
     /// s.push_str("bar");
-    /// assert_eq!(s, "foobar");
+    ///
+    /// assert_eq!("foobar", s);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -702,13 +772,15 @@ impl String {
         self.vec.extend_from_slice(string.as_bytes())
     }
 
-    /// Returns the number of bytes that this string buffer can hold without
+    /// Returns this `String`'s capacity, in bytes.
-    /// reallocating.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let s = String::with_capacity(10);
+    ///
     /// assert!(s.capacity() >= 10);
     /// ```
     #[inline]
@@ -717,9 +789,16 @@ impl String {
         self.vec.capacity()
     }
 
-    /// Reserves capacity for at least `additional` more bytes to be inserted
+    /// Ensures that this `String`'s capacity is at least `additional` bytes
-    /// in the given `String`. The collection may reserve more space to avoid
+    /// larger than its length.
-    /// frequent reallocations.
+    ///
+    /// The capacity may be increased by more than `additional` bytes if it
+    /// chooses, to prevent frequent reallocations.
+    ///
+    /// If you do not want this "at least" behavior, see the [`reserve_exact()`]
+    /// method.
+    ///
+    /// [`reserve_exact()`]: #method.reserve_exact
     ///
     /// # Panics
     ///
@@ -727,24 +806,46 @@ impl String {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::new();
+    ///
     /// s.reserve(10);
+    ///
     /// assert!(s.capacity() >= 10);
     /// ```
+    ///
+    /// This may not actually increase the capacity:
+    ///
+    /// ```
+    /// let mut s = String::with_capacity(10);
+    /// s.push('a');
+    /// s.push('b');
+    ///
+    /// // s now has a length of 2 and a capacity of 10
+    /// assert_eq!(2, s.len());
+    /// assert_eq!(10, s.capacity());
+    ///
+    /// // Since we already have an extra 8 capacity, calling this...
+    /// s.reserve(8);
+    ///
+    /// // ... doesn't actually increase.
+    /// assert_eq!(10, s.capacity());
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn reserve(&mut self, additional: usize) {
         self.vec.reserve(additional)
     }
 
-    /// Reserves the minimum capacity for exactly `additional` more bytes to be
+    /// Ensures that this `String`'s capacity is `additional` bytes
-    /// inserted in the given `String`. Does nothing if the capacity is already
+    /// larger than its length.
-    /// sufficient.
     ///
-    /// Note that the allocator may give the collection more space than it
+    /// Consider using the [`reserve()`] method unless you absolutely know
-    /// requests. Therefore capacity can not be relied upon to be precisely
+    /// better than the allocator.
-    /// minimal. Prefer `reserve` if future insertions are expected.
+    ///
+    /// [`reserve()`]: #method.reserve
     ///
     /// # Panics
     ///
@@ -752,27 +853,53 @@ impl String {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::new();
+    ///
     /// s.reserve_exact(10);
+    ///
     /// assert!(s.capacity() >= 10);
     /// ```
+    ///
+    /// This may not actually increase the capacity:
+    ///
+    /// ```
+    /// let mut s = String::with_capacity(10);
+    /// s.push('a');
+    /// s.push('b');
+    ///
+    /// // s now has a length of 2 and a capacity of 10
+    /// assert_eq!(2, s.len());
+    /// assert_eq!(10, s.capacity());
+    ///
+    /// // Since we already have an extra 8 capacity, calling this...
+    /// s.reserve_exact(8);
+    ///
+    /// // ... doesn't actually increase.
+    /// assert_eq!(10, s.capacity());
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn reserve_exact(&mut self, additional: usize) {
         self.vec.reserve_exact(additional)
     }
 
-    /// Shrinks the capacity of this string buffer to match its length.
+    /// Shrinks the capacity of this `String` to match its length.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("foo");
+    ///
     /// s.reserve(100);
     /// assert!(s.capacity() >= 100);
+    ///
     /// s.shrink_to_fit();
-    /// assert_eq!(s.capacity(), 3);
+    /// assert_eq!(3, s.capacity());
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -780,16 +907,20 @@ impl String {
         self.vec.shrink_to_fit()
     }
 
-    /// Adds the given character to the end of the string.
+    /// Appends the given `char` to the end of this `String`.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("abc");
+    ///
     /// s.push('1');
     /// s.push('2');
     /// s.push('3');
-    /// assert_eq!(s, "abc123");
+    ///
+    /// assert_eq!("abc123", s);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -815,13 +946,16 @@ impl String {
         }
     }
 
-    /// Works with the underlying buffer as a byte slice.
+    /// Returns a byte slice of this `String`'s contents.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let s = String::from("hello");
-    /// assert_eq!(s.as_bytes(), [104, 101, 108, 108, 111]);
+    ///
+    /// assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -829,19 +963,25 @@ impl String {
         &self.vec
     }
 
-    /// Shortens a string to the specified length.
+    /// Shortens this `String` to the specified length.
     ///
     /// # Panics
     ///
-    /// Panics if `new_len` > current length,
+    /// Panics if `new_len` > current length, or if `new_len` does not lie on a
-    /// or if `new_len` is not a character boundary.
+    /// [`char`] boundary.
+    ///
+    /// [`char`]: ../primitive.char.html
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("hello");
+    ///
     /// s.truncate(2);
-    /// assert_eq!(s, "he");
+    ///
+    /// assert_eq!("he", s);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -851,15 +991,20 @@ impl String {
     }
 
     /// Removes the last character from the string buffer and returns it.
-    /// Returns `None` if this string buffer is empty.
+    ///
+    /// Returns `None` if this `String` is empty.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("foo");
+    ///
     /// assert_eq!(s.pop(), Some('o'));
     /// assert_eq!(s.pop(), Some('o'));
     /// assert_eq!(s.pop(), Some('f'));
+    ///
     /// assert_eq!(s.pop(), None);
     /// ```
     #[inline]
@@ -877,23 +1022,25 @@ impl String {
         Some(ch)
     }
 
-    /// Removes the character from the string buffer at byte position `idx` and
+    /// Removes a `char` from this `String` at a byte position and returns it.
-    /// returns it.
     ///
-    /// # Warning
+    /// This is an `O(n)` operation, as it requires copying every element in the
-    ///
-    /// This is an O(n) operation as it requires copying every element in the
     /// buffer.
     ///
     /// # Panics
     ///
-    /// If `idx` does not lie on a character boundary, or if it is out of
+    /// Panics if `idx` is larger than the `String`'s length, or if it does not
-    /// bounds, then this function will panic.
+    /// lie on a [`char`] boundary.
+    ///
+    /// [`char`]: ../primitive.char.html
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("foo");
+    ///
     /// assert_eq!(s.remove(0), 'f');
     /// assert_eq!(s.remove(1), 'o');
     /// assert_eq!(s.remove(0), 'o');
@@ -915,17 +1062,31 @@ impl String {
         ch
     }
 
-    /// Inserts a character into the string buffer at byte position `idx`.
+    /// Inserts a character into this `String` at a byte position.
     ///
-    /// # Warning
+    /// This is an `O(n)` operation as it requires copying every element in the
-    ///
-    /// This is an O(n) operation as it requires copying every element in the
     /// buffer.
     ///
     /// # Panics
     ///
-    /// If `idx` does not lie on a character boundary or is out of bounds, then
+    /// Panics if `idx` is larger than the `String`'s length, or if it does not
-    /// this function will panic.
+    /// lie on a [`char`] boundary.
+    ///
+    /// [`char`]: ../primitive.char.html
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// let mut s = String::with_capacity(3);
+    ///
+    /// s.insert(0, 'f');
+    /// s.insert(1, 'o');
+    /// s.insert(2, 'o');
+    ///
+    /// assert_eq!("foo", s);
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn insert(&mut self, idx: usize, ch: char) {
@@ -947,18 +1108,26 @@ impl String {
         }
     }
 
-    /// Views the string buffer as a mutable sequence of bytes.
+    /// Returns a mutable reference to the contents of this `String`.
     ///
-    /// This is unsafe because it does not check
+    /// # Safety
-    /// to ensure that the resulting string will be valid UTF-8.
+    ///
+    /// This function is unsafe because it does not check that the bytes passed
+    /// to it are valid UTF-8. If this constraint is violated, it may cause
+    /// memory unsafety issues with future users of the `String`, as the rest of
+    /// the standard library assumes that `String`s are valid UTF-8.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("hello");
+    ///
     /// unsafe {
     ///     let vec = s.as_mut_vec();
-    ///     assert!(vec == &[104, 101, 108, 108, 111]);
+    ///     assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);
+    ///
     ///     vec.reverse();
     /// }
     /// assert_eq!(s, "olleh");
@@ -969,12 +1138,15 @@ impl String {
         &mut self.vec
     }
 
-    /// Returns the number of bytes in this string.
+    /// Returns the length of this `String`, in bytes.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
-    /// let a = "foo".to_string();
+    /// let a = String::from("foo");
+    ///
     /// assert_eq!(a.len(), 3);
     /// ```
     #[inline]
@@ -983,13 +1155,18 @@ impl String {
         self.vec.len()
     }
 
-    /// Returns true if the string contains no bytes
+    /// Returns `true` if this `String` has a length of zero.
+    ///
+    /// Returns `false` otherwise.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut v = String::new();
     /// assert!(v.is_empty());
+    ///
     /// v.push('a');
     /// assert!(!v.is_empty());
     /// ```
@@ -999,14 +1176,23 @@ impl String {
         self.len() == 0
     }
 
-    /// Truncates the string, returning it to 0 length.
+    /// Truncates this `String`, removing all contents.
+    ///
+    /// While this means the `String` will have a length of zero, it does not
+    /// touch its capacity.
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
-    /// let mut s = "foo".to_string();
+    /// let mut s = String::from("foo");
+    ///
     /// s.clear();
+    ///
     /// assert!(s.is_empty());
+    /// assert_eq!(0, s.len());
+    /// assert_eq!(3, s.capacity());
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1020,11 +1206,15 @@ impl String {
     ///
     /// # Panics
     ///
-    /// Panics if the starting point or end point are not on character boundaries,
+    /// Panics if the starting point or end point do not lie on a [`char`]
-    /// or if they are out of bounds.
+    /// boundary, or if they're out of bounds.
+    ///
+    /// [`char`]: ../primitive.char.html
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut s = String::from("α is alpha, β is beta");
     /// let beta_offset = s.find('β').unwrap_or(s.len());
@@ -1066,9 +1256,19 @@ impl String {
         }
     }
 
-    /// Converts the string into `Box<str>`.
+    /// Converts this `String` into a `Box<str>`.
     ///
-    /// Note that this will drop any excess capacity.
+    /// This will drop any excess capacity.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// let s = String::from("hello");
+    ///
+    /// let b = s.into_boxed_str();
+    /// ```
     #[stable(feature = "box_str", since = "1.4.0")]
     pub fn into_boxed_str(self) -> Box<str> {
         let slice = self.vec.into_boxed_slice();