Rollup merge of rust-lang#116807 - seanlinsley:patch-2, r=thomcc

Improve rewind documentation

The persistent use of an internal cursor for readers is expected for buffer data types that aren't read all at once, but for files it leads to the confusing situation where calling `read_to_end` on the same file handle multiple times only returns the contents of the file for the first call. This PR adds a note to the documentation clarifying that in that case, `rewind()` must first be called.

I'm unsure if this is the right location for the docs update. Maybe it should also be duplicated on `File`?

Author: matthiaskrgr

library/std/src/io/mod.rs

@@ -556,6 +556,10 @@ where
 /// therefore, using something that implements [`BufRead`], such as
 /// [`BufReader`], will be more efficient.
 ///
+/// Repeated calls to the reader use the same cursor, so for example
+/// calling `read_to_end` twice on a [`File`] will only return the file's
+/// contents once. It's recommended to first call `rewind()` in that case.
+///
 /// # Examples
 ///
 /// [`File`]s implement `Read`: