From 955829cee9a5bc5b07895200df50085225bca9f6 Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Sat, 29 Oct 2016 15:23:49 -0700
Subject: [PATCH] Add documentation to write! and writeln! on using both
 io::Write and fmt::Write

Various existing code does this, but the documentation doesn't explain
how to do it.
---
 src/libcore/macros.rs | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index e6c3f549ec8e6..dfd197a414865 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -348,6 +348,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 {
@@ -391,6 +406,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 {