Rollup merge of rust-lang#39233 - frewsxcv:upper-lower-docs, r=Guilla…

…umeGomez

Add more references between lowercase/uppercase operations.

None

src/libstd/ascii.rs

@@ -66,6 +66,11 @@ pub trait AsciiExt {
     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
     /// but non-ASCII letters are unchanged.
     ///
+    /// To uppercase the string in-place, use [`make_ascii_uppercase`].
+    ///
+    /// To uppercase ASCII characters in addition to non-ASCII characters, use
+    /// [`str::to_uppercase`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -77,6 +82,9 @@ pub trait AsciiExt {
     /// assert_eq!('A', ascii.to_ascii_uppercase());
     /// assert_eq!('❤', utf8.to_ascii_uppercase());
     /// ```
+    ///
+    /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase
+    /// [`str::to_uppercase`]: ../primitive.str.html#method.to_uppercase
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_ascii_uppercase(&self) -> Self::Owned;
 
@@ -85,6 +93,11 @@ pub trait AsciiExt {
     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
     /// but non-ASCII letters are unchanged.
     ///
+    /// To lowercase the string in-place, use [`make_ascii_lowercase`].
+    ///
+    /// To lowercase ASCII characters in addition to non-ASCII characters, use
+    /// [`str::to_lowercase`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -96,6 +109,9 @@ pub trait AsciiExt {
     /// assert_eq!('a', ascii.to_ascii_lowercase());
     /// assert_eq!('❤', utf8.to_ascii_lowercase());
     /// ```
+    ///
+    /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase
+    /// [`str::to_lowercase`]: ../primitive.str.html#method.to_lowercase
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_ascii_lowercase(&self) -> Self::Owned;
 
@@ -123,7 +139,11 @@ pub trait AsciiExt {
 
     /// Converts this type to its ASCII upper case equivalent in-place.
     ///
-    /// See `to_ascii_uppercase` for more information.
+    /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
+    /// but non-ASCII letters are unchanged.
+    ///
+    /// To return a new uppercased string without modifying the existing one, use
+    /// [`to_ascii_uppercase`].
     ///
     /// # Examples
     ///
@@ -136,12 +156,18 @@ pub trait AsciiExt {
     ///
     /// assert_eq!('A', ascii);
     /// ```
+    ///
+    /// [`to_ascii_uppercase`]: #tymethod.to_ascii_uppercase
     #[stable(feature = "ascii", since = "1.9.0")]
     fn make_ascii_uppercase(&mut self);
 
     /// Converts this type to its ASCII lower case equivalent in-place.
     ///
-    /// See `to_ascii_lowercase` for more information.
+    /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
+    /// but non-ASCII letters are unchanged.
+    ///
+    /// To return a new lowercased string without modifying the existing one, use
+    /// [`to_ascii_lowercase`].
     ///
     /// # Examples
     ///
@@ -154,6 +180,8 @@ pub trait AsciiExt {
     ///
     /// assert_eq!('a', ascii);
     /// ```
+    ///
+    /// [`to_ascii_lowercase`]: #tymethod.to_ascii_lowercase
     #[stable(feature = "ascii", since = "1.9.0")]
     fn make_ascii_lowercase(&mut self);
 }