@@ -65,12 +65,15 @@ pub struct Error;
6565/// A collection of methods that are required to format a message into a stream.
6666///
6767/// This trait is the type which this modules requires when formatting
68- /// information. This is similar to the standard library's `io::Write` trait,
68+ /// information. This is similar to the standard library's [ `io::Write`] trait,
6969/// but it is only intended for use in libcore.
7070///
7171/// This trait should generally not be implemented by consumers of the standard
72- /// library. The `write!` macro accepts an instance of `io::Write`, and the
73- /// `io::Write` trait is favored over implementing this trait.
72+ /// library. The [`write!`] macro accepts an instance of [`io::Write`], and the
73+ /// [`io::Write`] trait is favored over implementing this trait.
74+ ///
75+ /// [`write!`]: ../../std/macro.write.html
76+ /// [`io::Write`]: ../../std/io/trait.Write.html
7477#[ stable( feature = "rust1" , since = "1.0.0" ) ]
7578pub trait Write {
7679 /// Writes a slice of bytes into this writer, returning whether the write
@@ -82,29 +85,79 @@ pub trait Write {
8285///
8386/// # Errors
8487///
85- /// This function will return an instance of `Error` on error.
88+ /// This function will return an instance of [`Error`] on error.
89+ ///
90+ /// [`Error`]: struct.Error.html
91+ ///
92+ /// # Examples
93+ ///
94+ /// ```
95+ /// use std::fmt::{Error, Write};
96+ ///
97+ /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
98+ /// f.write_str(s)
99+ /// }
100+ ///
101+ /// let mut buf = String::new();
102+ /// writer(&mut buf, "hola").unwrap();
103+ /// assert_eq!(&buf, "hola");
104+ /// ```
86105#[ stable( feature = "rust1" , since = "1.0.0" ) ]
87106 fn write_str ( & mut self , s : & str ) -> Result ;
88107
89- /// Writes a `char` into this writer, returning whether the write succeeded.
108+ /// Writes a [ `char`] into this writer, returning whether the write succeeded.
90109///
91- /// A single `char` may be encoded as more than one byte.
110+ /// A single [ `char`] may be encoded as more than one byte.
92111/// This method can only succeed if the entire byte sequence was successfully
93112/// written, and this method will not return until all data has been
94113/// written or an error occurs.
95114///
96115/// # Errors
97116///
98- /// This function will return an instance of `Error` on error.
117+ /// This function will return an instance of [`Error`] on error.
118+ ///
119+ /// [`char`]: ../../std/primitive.char.html
120+ /// [`Error`]: struct.Error.html
121+ ///
122+ /// # Examples
123+ ///
124+ /// ```
125+ /// use std::fmt::{Error, Write};
126+ ///
127+ /// fn writer<W: Write>(f: &mut W, c: char) -> Result<(), Error> {
128+ /// f.write_char(c)
129+ /// }
130+ ///
131+ /// let mut buf = String::new();
132+ /// writer(&mut buf, 'a').unwrap();
133+ /// writer(&mut buf, 'b').unwrap();
134+ /// assert_eq!(&buf, "ab");
135+ /// ```
99136#[ stable( feature = "fmt_write_char" , since = "1.1.0" ) ]
100137 fn write_char ( & mut self , c : char ) -> Result {
101138 self . write_str ( c. encode_utf8 ( & mut [ 0 ; 4 ] ) )
102139 }
103140
104- /// Glue for usage of the `write!` macro with implementors of this trait.
141+ /// Glue for usage of the [ `write!`] macro with implementors of this trait.
105142///
106143/// This method should generally not be invoked manually, but rather through
107- /// the `write!` macro itself.
144+ /// the [`write!`] macro itself.
145+ ///
146+ /// [`write!`]: ../../std/macro.write.html
147+ ///
148+ /// # Examples
149+ ///
150+ /// ```
151+ /// use std::fmt::{Error, Write};
152+ ///
153+ /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
154+ /// f.write_fmt(format_args!("{}", s))
155+ /// }
156+ ///
157+ /// let mut buf = String::new();
158+ /// writer(&mut buf, "world").unwrap();
159+ /// assert_eq!(&buf, "world");
160+ /// ```
108161#[ stable( feature = "rust1" , since = "1.0.0" ) ]
109162 fn write_fmt ( & mut self , args : Arguments ) -> Result {
110163 // This Adapter is needed to allow `self` (of type `&mut
0 commit comments