Document buffering behaviour fot `Stdout(Lock)`

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 https://github.com/rust-lang/rust/issues/23818) but I'd like to clarify how it is buffered, and how one should deal with it.

Start with the linked Stdout and StdoutLock documentation, then read the referenced LineWriterShim comments and the prior buffering discussion. Update the documentation to explain how stdout is buffered and how callers should deal with that behavior.