str::lines and BufRead::lines: document trailing bare cr behaviour

Apropos discussion here
  rust-lang#91047 (comment)

Sadly, str::lines gets this wrong.  I think it is probably too late to
fix this, so document it instead.

Author: ijackson

library/core/src/str/mod.rs

@@ -899,6 +899,19 @@ impl str {
     ///
     /// assert_eq!(None, lines.next());
     /// ```
+    ///
+    /// Handling of a trailing bare CR is, sadly, anomalous:
+    /// (`std::io::BufRead::lines` handles this case correctly.)
+    ///
+    /// ```
+    /// let text = "foo\nbar\r";
+    /// let mut lines = text.lines();
+    ///
+    /// assert_eq!(Some("foo"), lines.next());
+    /// assert_eq!(Some("bar"), lines.next()); // should really return "bar\r"
+    ///
+    /// assert_eq!(None, lines.next());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     pub fn lines(&self) -> Lines<'_> {

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 handled correctly:
+    ///
+    /// ```
+    /// 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"))); // bare CR is not a newline
+    /// assert_eq!(lines_iter.next(), None);
+    /// ```
+    ///
     /// # Errors
     ///
     /// Each line of the iterator has the same error semantics as [`BufRead::read_line`].