From 0bbbe892f7efb4d1a1c04341757ed285690c76dc Mon Sep 17 00:00:00 2001
From: Nicholas Nethercote <n.nethercote@gmail.com>
Date: Mon, 16 Dec 2024 15:55:23 +1100
Subject: [PATCH] Improve comments on keywords.

To make it clear which predicates apply to which keywords.

Also reorder the predicates a little to match the order of the keyword
list.
---
 compiler/rustc_ast/src/token.rs   |  3 ++-
 compiler/rustc_span/src/symbol.rs | 29 ++++++++++++++++++-----------
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/compiler/rustc_ast/src/token.rs b/compiler/rustc_ast/src/token.rs
index 9798176a7ecf..d82b22f4ffbc 100644
--- a/compiler/rustc_ast/src/token.rs
+++ b/compiler/rustc_ast/src/token.rs
@@ -904,7 +904,8 @@ impl Token {
         self.is_non_raw_ident_where(|id| id.name == kw)
     }
 
-    /// Returns `true` if the token is a given keyword, `kw` or if `case` is `Insensitive` and this token is an identifier equal to `kw` ignoring the case.
+    /// Returns `true` if the token is a given keyword, `kw` or if `case` is `Insensitive` and this
+    /// token is an identifier equal to `kw` ignoring the case.
     pub fn is_keyword_case(&self, kw: Symbol, case: Case) -> bool {
         self.is_keyword(kw)
             || (case == Case::Insensitive
diff --git a/compiler/rustc_span/src/symbol.rs b/compiler/rustc_span/src/symbol.rs
index 4f178e715c0b..6a855a09d810 100644
--- a/compiler/rustc_span/src/symbol.rs
+++ b/compiler/rustc_span/src/symbol.rs
@@ -20,11 +20,12 @@ mod tests;
 
 // The proc macro code for this is in `compiler/rustc_macros/src/symbols.rs`.
 symbols! {
-    // If you modify this list, adjust `is_any_keyword`, `is_reserved_ident`,
-    // `is_used_keyword`/`is_unused_keyword` and `AllKeywords`.
-    // But this should rarely be necessary if the keywords are kept in alphabetic order.
+    // If you modify this list, adjust the predicates mentioned in comments
+    // below. But this should rarely be necessary if the keywords are kept in
+    // alphabetic order.
     Keywords {
         // Keywords that are used in stable Rust.
+        // Predicates: `is_any_keyword`, `is_used_keyword_always`/`is_reserved`
         As:                 "as",
         Break:              "break",
         Const:              "const",
@@ -62,6 +63,7 @@ symbols! {
         While:              "while",
 
         // Keywords that are used in unstable Rust or reserved for future use.
+        // Predicates: `is_any_keyword`, `is_unused_keyword_always`/`is_reserved`
         Abstract:           "abstract",
         Become:             "become",
         Box:                "box",
@@ -76,15 +78,20 @@ symbols! {
         Yield:              "yield",
 
         // Edition-specific keywords that are used in stable Rust.
+        // Predicates: `is_any_keyword`, `is_used_keyword_conditional`/`is_reserved` (if the
+        // edition suffices)
         Async:              "async", // >= 2018 Edition only
         Await:              "await", // >= 2018 Edition only
         Dyn:                "dyn", // >= 2018 Edition only
 
         // Edition-specific keywords that are used in unstable Rust or reserved for future use.
+        // Predicates: `is_any_keyword`, `is_unused_keyword_conditional`/`is_reserved` (if the
+        // edition suffices)
         Gen:                "gen", // >= 2024 Edition only
         Try:                "try", // >= 2018 Edition only
 
         // Weak keywords, have special meaning only in specific contexts.
+        // Predicates: `is_any_keyword`
         Auto:               "auto",
         Builtin:            "builtin",
         Catch:              "catch",
@@ -2586,27 +2593,27 @@ impl Symbol {
         self >= kw::As && self <= kw::Yeet
     }
 
-    fn is_reserved_ident(self) -> bool {
-        self == sym::dollar_crate || self == sym::underscore
-    }
-
     fn is_used_keyword_always(self) -> bool {
         self >= kw::As && self <= kw::While
     }
 
-    fn is_used_keyword_conditional(self, edition: impl FnOnce() -> Edition) -> bool {
-        (self >= kw::Async && self <= kw::Dyn) && edition() >= Edition::Edition2018
-    }
-
     fn is_unused_keyword_always(self) -> bool {
         self >= kw::Abstract && self <= kw::Yield
     }
 
+    fn is_used_keyword_conditional(self, edition: impl FnOnce() -> Edition) -> bool {
+        (self >= kw::Async && self <= kw::Dyn) && edition() >= Edition::Edition2018
+    }
+
     fn is_unused_keyword_conditional(self, edition: impl Copy + FnOnce() -> Edition) -> bool {
         self == kw::Gen && edition().at_least_rust_2024()
             || self == kw::Try && edition().at_least_rust_2018()
     }
 
+    fn is_reserved_ident(self) -> bool {
+        self == sym::dollar_crate || self == sym::underscore
+    }
+
     pub fn is_reserved(self, edition: impl Copy + FnOnce() -> Edition) -> bool {
         self.is_reserved_ident()
             || self.is_used_keyword_always()