std: Add a note about the print! macro and output buffering

[richo]

cc #23818

[rust-highfive]

r? @huonw

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

[barosl]

Shouldn't this be buffered instead?

[richo]

Err, yeah. Thanks for the catch!

[tanadeau]

It would be helpful if this had a reference to the flush() method on the Write trait and an example of the use of print! that needs flushing (like a prompt).

[alexcrichton]

I think this may want to be rephrased to not mention unix and also mention "line buffering" somewhere, perhaps:

Note that stdout is frequently line-buffered by default so it may be necessary to use io::stdout().flush() to ensure the output is emitted immediately.

[richo]

Totally reasonable, is there markup to make it actually linkify io::stdout ? (Will it do this by default? That would be amazing)

[alexcrichton]

Unfortunately, no, there is no default auto-linking, but you can always do it manually via [foo](../bar/baz.html)

[richo]

I updated the doc comment. Including the link inline made it no longer possible to just copy the invocation out of the comment, which I felt outweighed the benefit.

[alexcrichton]

Can you match the surrounding style and wrap this to 80-characters as well? Also, can you put io::stdout().flush() in backticks as well?

[richo]

Done, apologies somehow tw got screwed up in my editor.

[alexcrichton]

@bors: r+ 6e8693b rollup

Thanks!