Rollup merge of #40335 - tbu-:pr_doc_str_to_somecase, r=steveklabnik

Document why `str.to_{lower,upper}case` return `String`

Fixes #39201.

src/libcollections/str.rs

@@ -1646,6 +1646,10 @@ pub fn replacen<'a, P: Pattern<'a>>(&'a self, pat: P, to: &str, count: usize) ->
     /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property
     /// `Lowercase`.
     ///
+    /// Since some characters can expand into multiple characters when changing
+    /// the case, this function returns a [`String`] instead of modifying the
+    /// parameter in-place.
+    ///
     /// [`String`]: string/struct.String.html
     ///
     /// # Examples
@@ -1718,6 +1722,10 @@ fn case_ignoreable_then_cased<I: Iterator<Item = char>>(iter: I) -> bool {
     /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property
     /// `Uppercase`.
     ///
+    /// Since some characters can expand into multiple characters when changing
+    /// the case, this function returns a [`String`] instead of modifying the
+    /// parameter in-place.
+    ///
     /// [`String`]: string/struct.String.html
     ///
     /// # Examples