Rollup merge of rust-lang#37472 - joshtriplett:doc-fmt-write-io-write, r=brson

Document convention for using both fmt::Write and io::Write

Using a trait's methods (like `Write::write_fmt` as used in `writeln!` and other macros) requires importing that trait directly (not just the module containing it).  Both `fmt::Write` and `io::Write` provide compatible `Write::write_fmt` methods, and code can use `writeln!` and other macros on both an object implementing `fmt::Write` (such as a `String`) and an object implementing `io::Write` (such as `Stderr`).  However, importing both `Write` traits produces an error due to the name conflict.

The convention I've seen renames both of them on import, to `FmtWrite` and `IoWrite` respectively.  Document that convention in the Rust documentation for `write!` and `writeln!`, with examples.

Author: eddyb

src/libcore/macros.rs

@@ -350,6 +350,21 @@ macro_rules! try {
 ///
 /// assert_eq!(w, b"testformatted arguments");
 /// ```
+///
+/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
+/// implementing either, as objects do not typically implement both. However, the module must
+/// import the traits qualified so their names do not conflict:
+///
+/// ```
+/// use std::fmt::Write as FmtWrite;
+/// use std::io::Write as IoWrite;
+///
+/// let mut s = String::new();
+/// let mut v = Vec::new();
+/// write!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt
+/// write!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt
+/// assert_eq!(v, b"s = \"abc 123\"");
+/// ```
 #[macro_export]
 #[stable(feature = "core", since = "1.6.0")]
 macro_rules! write {
@@ -394,6 +409,21 @@ macro_rules! write {
 ///
 /// assert_eq!(&w[..], "test\nformatted arguments\n".as_bytes());
 /// ```
+///
+/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
+/// implementing either, as objects do not typically implement both. However, the module must
+/// import the traits qualified so their names do not conflict:
+///
+/// ```
+/// use std::fmt::Write as FmtWrite;
+/// use std::io::Write as IoWrite;
+///
+/// let mut s = String::new();
+/// let mut v = Vec::new();
+/// writeln!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt
+/// writeln!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt
+/// assert_eq!(v, b"s = \"abc 123\\n\"\n");
+/// ```
 #[macro_export]
 #[stable(feature = "rust1", since = "1.0.0")]
 macro_rules! writeln {