diff --git a/library/core/src/str/mod.rs b/library/core/src/str/mod.rs
index cd5ed35be79ba..10276eb2ec9c6 100644
--- a/library/core/src/str/mod.rs
+++ b/library/core/src/str/mod.rs
@@ -899,6 +899,18 @@ impl str {
     ///
     /// assert_eq!(None, lines.next());
     /// ```
+    ///
+    /// Unlike [`std::io::BufRead::lines`], trailing bare CR is handled as a newline:
+    ///
+    /// ```
+    /// let text = "foo\nbar\r";
+    /// let mut lines = text.lines();
+    ///
+    /// assert_eq!(Some("foo"), lines.next());
+    /// assert_eq!(Some("bar"), lines.next()); // does not return "bar\r"
+    ///
+    /// assert_eq!(None, lines.next());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     pub fn lines(&self) -> Lines<'_> {
diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs
index 8cc91566418dc..e47d0a961141b 100644
--- a/library/std/src/io/mod.rs
+++ b/library/std/src/io/mod.rs
@@ -2281,6 +2281,19 @@ pub trait BufRead: Read {
     /// assert_eq!(lines_iter.next(), None);
     /// ```
     ///
+    /// Unlike [`str::lines`], trailing bare CR is not handled as a newline:
+    ///
+    /// ```
+    /// use std::io::{self, BufRead};
+    ///
+    /// let cursor = io::Cursor::new(b"lorem\nipsum\r");
+    ///
+    /// let mut lines_iter = cursor.lines().map(|l| l.unwrap());
+    /// assert_eq!(lines_iter.next(), Some(String::from("lorem")));
+    /// assert_eq!(lines_iter.next(), Some(String::from("ipsum\r"))); // does not return "ipsum"
+    /// assert_eq!(lines_iter.next(), None);
+    /// ```
+    ///
     /// # Errors
     ///
     /// Each line of the iterator has the same error semantics as [`BufRead::read_line`].