Rollup merge of #93392 - GKFX:char-docs, r=scottmcm

Clarify documentation on char::MAX

As mentioned in https://github.com/rust-lang/rust/issues/91836#issuecomment-994106874, the documentation on `char::MAX` is not quite correct – USVs are not "only ones within a certain range", they are code points _outside_ a certain range. I have corrected this and given the actual numbers as there is no reason to hide them.

2 files changed, 22 insertions, 12 deletions

diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs
index 7250dca2adf..c4c0a5a6c78 100644
--- a/library/core/src/char/methods.rs
+++ b/library/core/src/char/methods.rs
@@ -9,14 +9,19 @@ use super::*;
 
 #[lang = "char"]
 impl char {
-    /// The highest valid code point a `char` can have.
+    /// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
     ///
-    /// A `char` is a [Unicode Scalar Value], which means that it is a [Code
-    /// Point], but only ones within a certain range. `MAX` is the highest valid
-    /// code point that's a valid [Unicode Scalar Value].
+    /// # Examples
+    ///
+    /// ```
+    /// # fn something_which_returns_char() -> char { 'a' }
+    /// let c: char = something_which_returns_char();
+    /// assert!(c <= char::MAX);
     ///
-    /// [Unicode Scalar Value]: https://www.unicode.org/glossary/#unicode_scalar_value
-    /// [Code Point]: https://www.unicode.org/glossary/#code_point
+    /// let value_at_max = char::MAX as u32;
+    /// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}'));
+    /// assert_eq!(char::from_u32(value_at_max + 1), None);
+    /// ```
     #[stable(feature = "assoc_char_consts", since = "1.52.0")]
     pub const MAX: char = '\u{10ffff}';
 
diff --git a/library/core/src/char/mod.rs b/library/core/src/char/mod.rs
index f65f84e93ae..9364ac4f3ec 100644
--- a/library/core/src/char/mod.rs
+++ b/library/core/src/char/mod.rs
@@ -89,14 +89,19 @@ const MAX_THREE_B: u32 = 0x10000;
     Cn  Unassigned              a reserved unassigned code point or a noncharacter
 */
 
-/// The highest valid code point a `char` can have.
+/// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
 ///
-/// A [`char`] is a [Unicode Scalar Value], which means that it is a [Code
-/// Point], but only ones within a certain range. `MAX` is the highest valid
-/// code point that's a valid [Unicode Scalar Value].
+/// # Examples
 ///
-/// [Unicode Scalar Value]: https://www.unicode.org/glossary/#unicode_scalar_value
-/// [Code Point]: https://www.unicode.org/glossary/#code_point
+/// ```
+/// # fn something_which_returns_char() -> char { 'a' }
+/// let c: char = something_which_returns_char();
+/// assert!(c <= char::MAX);
+///
+/// let value_at_max = char::MAX as u32;
+/// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}'));
+/// assert_eq!(char::from_u32(value_at_max + 1), None);
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub const MAX: char = char::MAX;