Add warning to BufWriter documentation

[gllghr]

When using BufWriter, it is very easy to unintentionally ignore errors, because errors which occur when flushing buffered data when the BufWriter is dropped are ignored. This has been noted in a couple places: #32677, #37045.

There has been some discussion about how to fix this problem in #32677, but no solution seems likely to land in the near future. For now, anyone who wishes to have robust error handling must remember to manually call flush() on a BufWriter before it is dropped. Until a permanent fix is in place, it seems worthwhile to add a warning to that effect to the documentation.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @BurntSushi (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[BurntSushi]

Adding this warning seems sensible enough to me. I think the only question is whether this now makes the behavior part of the public API, and if so, whether we're comfortable with that or not. I kind of feel like it's already the de facto API, so these docs are just recognizing that.

Anyone else from @rust-lang/libs want to weigh in?

[alexcrichton]

Seems like a fine change to me!

[steveklabnik]

@bors: r+ rollup

thank you!

[bors]

📌 Commit c6b280e has been approved by steveklabnik