call out explicitly that general read needs to be called with an initialized buffer

1 files changed, 10 insertions, 1 deletions

diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 917199f8ea8..7fba844897f 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -506,9 +506,18 @@ pub trait Read {
     ///
     /// No guarantees are provided about the contents of `buf` when this
     /// function is called, implementations cannot rely on any property of the
-    /// contents of `buf` being true. It is recommended that implementations
+    /// contents of `buf` being true. It is recommended that *implementations*
     /// only write data to `buf` instead of reading its contents.
     ///
+    /// Correspondingly, however, *users* of this trait may not assume any guarantees
+    /// about how the implementation uses `buf`. The trait is safe to implement,
+    /// so it is perfectly possible that the implementation might inspect that data.
+    /// As a caller, it is your responsibility to make sure that `buf` is initialized
+    /// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one
+    /// obtains via [`MaybeUninit<T>`]) is not safe, and can lead to undefined behavior.
+    ///
+    /// [`MaybeUninit<T>`]: ../mem/union.MaybeUninit.html
+    ///
     /// # Errors
     ///
     /// If this function encounters any form of I/O or other error, an error