Document std::string::ParseError

Part of #29376

1 files changed, 12 insertions, 1 deletions

diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs
index 9f09facdaf7..5a724473d61 100644
--- a/src/libcollections/string.rs
+++ b/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 {}