Auto merge of #142299 - fmease:rollup-u86s80a, r=fmease

Rollup of 16 pull requests

Successful merges:

 - rust-lang/rust#134442 (Specify the behavior of `file!`)
 - rust-lang/rust#140372 (Exhaustively handle parsed attributes in CheckAttr)
 - rust-lang/rust#140766 (Stabilize keylocker)
 - rust-lang/rust#141642 (Note the version and PR of removed features when using it)
 - rust-lang/rust#141818 (Don't create .msi installer for gnullvm hosts)
 - rust-lang/rust#141909 (Add central execution context to bootstrap)
 - rust-lang/rust#141992 (use `#[naked]` for `__rust_probestack`)
 - rust-lang/rust#142101 (core::ptr: deduplicate more method docs)
 - rust-lang/rust#142102 (docs: Small clarification on the usage of read_to_string and read_to_end trait methods)
 - rust-lang/rust#142124 (Allow transmute casts in pre-runtime-MIR)
 - rust-lang/rust#142240 (deduplicate the rest of AST walker functions)
 - rust-lang/rust#142258 (platform-support.md: Mention specific Linux kernel version or later)
 - rust-lang/rust#142262 (Mark `core::slice::memchr` as `#[doc(hidden)]`)
 - rust-lang/rust#142271 (compiler: fn ptrs should hit different lints based on ABI)
 - rust-lang/rust#142275 (rustdoc: Refractor `clean_ty_generics`)
 - rust-lang/rust#142288 (const_eval: fix some outdated comments)

r? `@ghost`
`@rustbot` modify labels: rollup

1 files changed, 40 insertions, 0 deletions

diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs
index 20c82b64bcc..a9a24681e7c 100644
--- a/library/std/src/io/mod.rs
+++ b/library/std/src/io/mod.rs
@@ -917,6 +917,19 @@ pub trait Read {
     /// # }
     /// ```
     ///
+    /// # Usage Notes
+    ///
+    /// `read_to_end` attempts to read a source until EOF, but many sources are continuous streams
+    /// that do not send EOF. In these cases, `read_to_end` will block indefinitely. Standard input
+    /// is one such stream which may be finite if piped, but is typically continuous. For example,
+    /// `cat file | my-rust-program` will correctly terminate with an `EOF` upon closure of cat.
+    /// Reading user input or running programs that remain open indefinitely will never terminate
+    /// the stream with `EOF` (e.g. `yes | my-rust-program`).
+    ///
+    /// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
+    ///
+    ///[`read`]: Read::read
+    ///
     /// [`Vec::try_reserve`]: crate::vec::Vec::try_reserve
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
@@ -960,6 +973,19 @@ pub trait Read {
     /// (See also the [`std::fs::read_to_string`] convenience function for
     /// reading from a file.)
     ///
+    /// # Usage Notes
+    ///
+    /// `read_to_string` attempts to read a source until EOF, but many sources are continuous streams
+    /// that do not send EOF. In these cases, `read_to_string` will block indefinitely. Standard input
+    /// is one such stream which may be finite if piped, but is typically continuous. For example,
+    /// `cat file | my-rust-program` will correctly terminate with an `EOF` upon closure of cat.
+    /// Reading user input or running programs that remain open indefinitely will never terminate
+    /// the stream with `EOF` (e.g. `yes | my-rust-program`).
+    ///
+    /// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
+    ///
+    ///[`read`]: Read::read
+    ///
     /// [`std::fs::read_to_string`]: crate::fs::read_to_string
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
@@ -1262,6 +1288,20 @@ pub trait Read {
 ///     Ok(())
 /// }
 /// ```
+///
+/// # Usage Notes
+///
+/// `read_to_string` attempts to read a source until EOF, but many sources are continuous streams
+/// that do not send EOF. In these cases, `read_to_string` will block indefinitely. Standard input
+/// is one such stream which may be finite if piped, but is typically continuous. For example,
+/// `cat file | my-rust-program` will correctly terminate with an `EOF` upon closure of cat.
+/// Reading user input or running programs that remain open indefinitely will never terminate
+/// the stream with `EOF` (e.g. `yes | my-rust-program`).
+///
+/// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
+///
+///[`read`]: Read::read
+///
 #[stable(feature = "io_read_to_string", since = "1.65.0")]
 pub fn read_to_string<R: Read>(mut reader: R) -> Result<String> {
     let mut buf = String::new();