Update docs on Error struct. #29355

This adds a pretty contrived example of the usage of fmt::Error. I am
very open to suggestions for a better one.

I have also highlighted the fmt::Error vs std::error::Error.

r? @steveklabnik

diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index 8c3d3ce7d886b085c7b7964e726176475bdfbfff..d7c3cd4d3d9c964e9045f909e0445c2b648b9708 100644 (file)
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -81,6 +81,22 @@ pub mod rt {
 /// This type does not support transmission of an error other than that an error
 /// occurred. Any extra information must be arranged to be transmitted through
 /// some other means.
+///
+/// An important thing to remember is that the type `fmt::Error` should not be
+/// confused with `std::io::Error` or `std::error::Error`, which you may also
+/// have in scope.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::fmt::{self, write};
+///
+/// let mut output = String::new();
+/// match write(&mut output, format_args!("Hello {}!", "world")) {
+///     Err(fmt::Error) => panic!("An error occurred"),
+///     _ => (),
+/// }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct Error;