Document std::string::ParseError

src/libcollections/string.rs

@@ -1141,7 +1141,18 @@ impl ops::DerefMut for String {
     }
 }
 
-/// Error returned from `String::from`
+/// An error when parsing a `String`.
+///
+/// This `enum` is slightly awkward: it will never actually exist. This error is
+/// part of the type signature of the implementation of [`FromStr`] on
+/// [`String`]. The return type of [`from_str()`], requires that an error be
+/// defined, but, given that a [`String`] can always be made into a new
+/// [`String`] without error, this type will never actually be returned. As
+/// such, it is only here to satisfy said signature, and is useless otherwise.
+///
+/// [`FromStr`]: ../str/trait.FromStr.html
+/// [`String`]: struct.String.html
+/// [`from_str()`]: ../str/trait.FromStr.html#tymethod.from_str
 #[stable(feature = "str_parse_error", since = "1.5.0")]
 #[derive(Copy)]
 pub enum ParseError {}