Rollup merge of #131503 - theemathas:stdin_read_line_docs, r=Mark-Simulacrum

More clearly document Stdin::read_line

These are common pitfalls for beginners, so I think it's worth making the subtleties more visible.

library/std/src/io/stdio.rs

@@ -370,7 +370,12 @@ pub fn lock(&self) -> StdinLock<'static> {
     /// Locks this handle and reads a line of input, appending it to the specified buffer.
     ///
     /// For detailed semantics of this method, see the documentation on
-    /// [`BufRead::read_line`].
+    /// [`BufRead::read_line`]. In particular:
+    /// * Previous content of the buffer will be preserved. To avoid appending
+    ///   to the buffer, you need to [`clear`] it first.
+    /// * The trailing newline character, if any, is included in the buffer.
+    ///
+    /// [`clear`]: String::clear
     ///
     /// # Examples
     ///