From 14d3dbe292dc4ac590dabd0c33fe18edb7810be9 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Fri, 16 May 2014 22:40:38 -0700
Subject: [PATCH] core: Document FormatWriter and allow `write!`

This commit fills in the documentation holes for the FormatWriter trait which
were previously accidentally left blank. Additionally, this adds the `write_fmt`
method to the trait to allow usage of the `write!` macro with implementors of
the `FormatWriter` trait. This is not useful for consumers of the standard
library who should generally avoid the `FormatWriter` trait, but it is useful
for consumers of the core library who are not using the standard library.
---
 src/libcore/fmt/mod.rs                     | 36 +++++++++++++++++++---
 src/test/run-pass/colorful-write-macros.rs | 13 ++++++++
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index 979928c10ad..4e5affe0149 100644
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -43,16 +43,44 @@ pub mod rt;
 
 pub type Result = result::Result<(), FormatError>;
 
-/// dox
+/// The error type which is returned from formatting a message into a stream.
+///
+/// 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.
 pub enum FormatError {
-    /// dox
+    /// A generic write error occurred during formatting, no other information
+    /// is transmitted via this variant.
     WriteError,
 }
 
-/// dox
+/// A collection of methods that are required to format a message into a stream.
+///
+/// This trait is the type which this modules requires when formatting
+/// information. This is similar to the standard library's `io::Writer` trait,
+/// but it is only intended for use in libcore.
+///
+/// This trait should generally not be implemented by consumers of the standard
+/// library. The `write!` macro accepts an instance of `io::Writer`, and the
+/// `io::Writer` trait is favored over implementing this trait.
 pub trait FormatWriter {
-    /// dox
+    /// Writes a slice of bytes into this writer, returning whether the write
+    /// succeeded.
+    ///
+    /// This method can only succeed if the entire byte slice was successfully
+    /// written, and this method will not return until all data has been
+    /// written or an error occurs.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an instance of `FormatError` on error.
     fn write(&mut self, bytes: &[u8]) -> Result;
+
+    /// Glue for usage of the `write!` macro with implementors of this trait.
+    ///
+    /// This method should generally not be invoked manually, but rather through
+    /// the `write!` macro itself.
+    fn write_fmt(&mut self, args: &Arguments) -> Result { write(self, args) }
 }
 
 /// A struct to represent both where to emit formatting strings to and how they
diff --git a/src/test/run-pass/colorful-write-macros.rs b/src/test/run-pass/colorful-write-macros.rs
index 14c2a5ae6c8..724e57bdef2 100644
--- a/src/test/run-pass/colorful-write-macros.rs
+++ b/src/test/run-pass/colorful-write-macros.rs
@@ -14,12 +14,22 @@
 #![feature(macro_rules)]
 
 use std::io::MemWriter;
+use std::fmt;
+use std::fmt::FormatWriter;
 
 struct Foo<'a> {
     writer: &'a mut Writer,
     other: &'a str,
 }
 
+struct Bar;
+
+impl fmt::FormatWriter for Bar {
+    fn write(&mut self, _: &[u8]) -> fmt::Result {
+        Ok(())
+    }
+}
+
 fn borrowing_writer_from_struct_and_formatting_struct_field(foo: Foo) {
     write!(foo.writer, "{}", foo.other);
 }
@@ -29,4 +39,7 @@ fn main() {
     write!(&mut w as &mut Writer, "");
     write!(&mut w, ""); // should coerce
     println!("ok");
+
+    let mut s = Bar;
+    write!(&mut s, "test");
 }