Improve docs for write!/writeln! macros

[steveklabnik]

No description provided.

[rust-highfive]

r? @aturon

(rust_highfive has picked a reviewer for you, use r? to override)

[nagisa]

So, we gave up on making rustdoc do crosslinking? Who’s going to check these links do not break in the future?

[steveklabnik]

That ship sailed a long time ago.

[steveklabnik]

(that doesn't mean we couldn't add it in the future, but there are tons and tons and tons of these manual links all throughout the documentation)

[TimNN]

Actually I think the new docs are slightly incorrect, because write! will work for any type which has a write_fmt(self, Arguments) in scope, which is not only io::Write:

• http://doc.rust-lang.org/core/fmt/struct.Formatter.html#method.write_fmt
• http://doc.rust-lang.org/std/fmt/trait.Write.html#method.write_fmt
• http://doc.rust-lang.org/std/io/trait.Write.html#method.write_fmt

[steveklabnik]

@TimNN confirmed:

use std::fmt::Arguments;

struct Lol;

impl Lol {
    fn write_fmt(self, _: Arguments) -> std::fmt::Result {
        println!("called format");
        Ok(())
    }
}

fn main() {
    let l = Lol;
    write!(l, "yup").unwrap();
}

So, with that in mind, I'm not entirely sure how to document this, exactly. Seems like a fairly complex requirement...

[aturon]

@steveklabnik I believe the intent here is to be used as you say, and the stuff with formatting is largely an implementation artifact; I find this confusing every time I look at it.

@alexcrichton, do you think what @steveklabnik has here is a reasonable gloss?

r=me if so :)

[alexcrichton]

Yeah just because it'd a "duck typed I just call write_fmt" macro I don't think means that it should be documented as such. Perhaps this could just say "typically used with std::{fmt,io}::Write" or something like that to avoid saying "you must implement Write".

(the links are still broken btw)

[steveklabnik]

@alexcrichton they don't look broken to me?

[alexcrichton]

Aha! I see the syntax has changed now.

@bors: r+ ef9e542

[bors]

⌛ Testing commit ef9e542 with merge 439311d...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt