Document buffering behaviour fot Stdout(Lock)

[bertptrs]

Location

• Stdout documentation
• StdoutLock documentation`

Summary

The handles provided by std::io::stdout() are line-buffered, but there is nothing in the documentation suggesting this. The only mention of buffering for stdout in the documentation is the line

Each handle shares a global buffer of data to be written to the standard output stream. Access is also synchronized via a lock and explicit control over locking is available via the lock method.

I don't think this is very clear that stdout is buffered from this, nor that it uses line buffering.

Moreover, the comments for LineWriterShim suggest that this mechanism can be used to alternate between line buffering and block buffering for Stdout, which isn't mentioned in the documentation for Stdout at all.

I do not mean to relitigate whether or not it should be buffered (previous discussion in #23818) but I'd like to clarify how it is buffered, and how one should deal with it.

[the8472]

Looks like a duplicate of #106133

Additionally the behavior is not set in stone, there is some desire to change the buffering behavior: #60673