From 356616b2d136f47f2231b69cddc25d024271f2f6 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Tue, 14 May 2024 14:12:18 -0700
Subject: [PATCH] 2024: Document reserving `gen` keyword

---
 src/SUMMARY.md               |  1 +
 src/rust-2024/gen-keyword.md | 60 ++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 src/rust-2024/gen-keyword.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index e9e9e51..bbeeae7 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -45,3 +45,4 @@
   - [Public/private dependencies](rust-2024/public-private-dependencies.md)
   - [Cargo: Remove implicit features](rust-2024/cargo-remove-implicit-features.md)
   - [Rustfmt: Combine all delimited exprs as last argument](rust-2024/rustfmt-overflow-delimited-expr.md)
+  - [`gen` keyword](rust-2024/gen-keyword.md)
diff --git a/src/rust-2024/gen-keyword.md b/src/rust-2024/gen-keyword.md
new file mode 100644
index 0000000..73b2608
--- /dev/null
+++ b/src/rust-2024/gen-keyword.md
@@ -0,0 +1,60 @@
+# `gen` keyword
+
+🚧 The 2024 Edition has not yet been released and hence this section is still "under construction".
+More information may be found in the tracking issue at <https://github.com/rust-lang/rust/issues/123904>.
+
+## Summary
+
+- `gen` is a [reserved keyword].
+
+[reserved keyword]: ../../reference/keywords.html#reserved-keywords
+
+## Details
+
+The `gen` keyword has been reserved as part of [RFC #3513] to introduce "gen blocks" in a future release of Rust. `gen` blocks will provide a way to make it easier to write certain kinds of iterators. Reserving the keyword now will make it easier to stabilize `gen` blocks before the next edition.
+
+[RFC #3513]: https://rust-lang.github.io/rfcs/3513-gen-blocks.html
+
+## Migration
+
+Introducing the `gen` keyword can cause a problem for any identifiers that are already called `gen`. For example, any variable or function name called `gen` would clash with the new keyword. To work around this issue, Rust supports the `r#` prefix for a [raw identifier], which allows identifiers to overlap with keywords.
+
+The [`keyword_idents_2024`] lint will automatically modify any identifier named `gen` to be `r#gen` so that the code continues to work on both editions. This lint is part of the `rust-2024-compatibility` lint group, which will automatically be applied when running `cargo fix --edition`. To migrate your code to be Rust 2024 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+For example, this will change:
+
+```rust
+fn gen() {
+    println!("generating!");
+}
+
+fn main() {
+    gen();
+}
+```
+
+to be:
+
+```rust
+fn r#gen() {
+    println!("generating!");
+}
+
+fn main() {
+    r#gen();
+}
+```
+
+Alternatively, you can manually enable the lint to find places where the `gen` identifiers need to be modified to be `r#gen`:
+
+```rust
+// Add this to the root of your crate to do a manual migration.
+#![warn(keyword_idents_2024)]
+```
+
+[raw identifier]: ../../reference/identifiers.html#raw-identifiers
+[`keyword_idents_2024`]: ../../rustc/lints/listing/allowed-by-default.html#keyword-idents-2024