More clearly document Stdin::read_line

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

1 files changed, 6 insertions, 1 deletions

diff --git a/library/std/src/io/stdio.rs b/library/std/src/io/stdio.rs
index bf242e715bd..35b38ed783f 100644
--- a/library/std/src/io/stdio.rs
+++ b/library/std/src/io/stdio.rs
@@ -370,7 +370,12 @@ impl Stdin {
     /// 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
     ///