Rollup merge of #22989 - laijs:fix_FromStr_bool_comment, r=alexcrichton

Fix the return type in the comments.

An old commit 082bfde412 (\"Fallout of std::str stabilization\") removed
the example of FromStr::from_str(), this commit adds it back. But
the example of StrExt::parse() is still kept with an additinal note.

Signed-off-by: Lai Jiangshan <laijs@cn.fujitsu.com>

src/libcore/str/mod.rs

@@ -134,12 +134,23 @@ impl FromStr for bool {
 
     /// Parse a `bool` from a string.
     ///
-    /// Yields an `Option<bool>`, because `s` may or may not actually be
-    /// parseable.
+    /// Yields a `Result<bool, ParseBoolError>`, because `s` may or may not
+    /// actually be parseable.
     ///
     /// # Examples
     ///
     /// ```rust
+    /// use std::str::FromStr;
+    ///
+    /// assert_eq!(FromStr::from_str("true"), Ok(true));
+    /// assert_eq!(FromStr::from_str("false"), Ok(false));
+    /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
+    /// ```
+    ///
+    /// Note, in many cases, the StrExt::parse() which is based on
+    /// this FromStr::from_str() is more proper.
+    ///
+    /// ```rust
     /// assert_eq!("true".parse(), Ok(true));
     /// assert_eq!("false".parse(), Ok(false));
     /// assert!("not even a boolean".parse::<bool>().is_err());