@@ -457,11 +457,12 @@ macro_rules! r#try {
457457///
458458/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
459459/// implementing either, as objects do not typically implement both. However, the module must
460- /// import the traits qualified so their names do not conflict:
460+ /// avoid conflict between the trait names, such as by importing them as `_` or otherwise renaming
461+ /// them:
461462///
462463/// ```
463- /// use std::fmt::Write as FmtWrite ;
464- /// use std::io::Write as IoWrite ;
464+ /// use std::fmt::Write as _ ;
465+ /// use std::io::Write as _ ;
465466///
466467/// fn main() -> Result<(), Box<dyn std::error::Error>> {
467468/// let mut s = String::new();
@@ -474,6 +475,23 @@ macro_rules! r#try {
474475/// }
475476/// ```
476477///
478+ /// If you also need the trait names themselves, such as to implement one or both on your types,
479+ /// import the containing module and then name them with a prefix:
480+ ///
481+ /// ```
482+ /// # #![allow(unused_imports)]
483+ /// use std::fmt::{self, Write as _};
484+ /// use std::io::{self, Write as _};
485+ ///
486+ /// struct Example;
487+ ///
488+ /// impl fmt::Write for Example {
489+ /// fn write_str(&mut self, _s: &str) -> core::fmt::Result {
490+ /// unimplemented!();
491+ /// }
492+ /// }
493+ /// ```
494+ ///
477495/// Note: This macro can be used in `no_std` setups as well.
478496/// In a `no_std` setup you are responsible for the implementation details of the components.
479497///
@@ -526,25 +544,6 @@ macro_rules! write {
526544/// Ok(())
527545/// }
528546/// ```
529- ///
530- /// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
531- /// implementing either, as objects do not typically implement both. However, the module must
532- /// import the traits qualified so their names do not conflict:
533- ///
534- /// ```
535- /// use std::fmt::Write as FmtWrite;
536- /// use std::io::Write as IoWrite;
537- ///
538- /// fn main() -> Result<(), Box<dyn std::error::Error>> {
539- /// let mut s = String::new();
540- /// let mut v = Vec::new();
541- ///
542- /// writeln!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt
543- /// writeln!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt
544- /// assert_eq!(v, b"s = \"abc 123\\n\"\n");
545- /// Ok(())
546- /// }
547- /// ```
548547#[ macro_export]
549548#[ stable( feature = "rust1" , since = "1.0.0" ) ]
550549#[ cfg_attr( not( test) , rustc_diagnostic_item = "writeln_macro" ) ]
0 commit comments