From 3c8b798a085bce63236371e48941944546dbccd9 Mon Sep 17 00:00:00 2001
From: Bill Wagner <wiwagn@microsoft.com>
Date: Tue, 2 Jul 2024 14:23:05 -0400
Subject: [PATCH] Add stubs for new warnings and errors.

---
 .../compiler-messages/iterator-yield.md       | 41 +++++++++++++++++++
 docs/csharp/language-reference/toc.yml        |  3 ++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/csharp/language-reference/compiler-messages/iterator-yield.md

diff --git a/docs/csharp/language-reference/compiler-messages/iterator-yield.md b/docs/csharp/language-reference/compiler-messages/iterator-yield.md
new file mode 100644
index 0000000000000..ab659d56b3b20
--- /dev/null
+++ b/docs/csharp/language-reference/compiler-messages/iterator-yield.md
@@ -0,0 +1,41 @@
+---
+title: Errors and warnings for iterator methods and `yield return`
+description: Use article to diagnose and correct compiler errors and warnings when you write iterator methods that use `yield return` to enumerate a sequence of elements.
+f1_keywords:
+  - "CS9237"
+  - "CS9238"
+  - "CS9239"
+helpviewer_keywords:
+  - "CS9237"
+  - "CS9238"
+  - "CS9239"
+ms.date: 07/02/2024
+---
+# Errors and warnings related to the `yield return` statement and iterator methods
+
+There are numerous *errors* related to the `yield return` statement and iterator methods:
+
+<!-- The text in this list generates issues for Acrolinx, because they don't use contractions.
+That's by design. The text closely matches the text of the compiler error / warning for SEO purposes.
+ -->
+- [**CS9237**](#): *'yield return' should not be used in the body of a lock statement*
+- [**CS9238**](#): *Cannot use 'yield return' in an 'unsafe' block*
+- [**CS9239**](#): *The `&` operator cannot be used on parameters or local variables in iterator methods.*
+
+In addition, the compiler might produce the following *warning* related to `lock` statements and thread synchronization:
+
+- [**CS9216**](#lock-warning): *A value of type `System.Threading.Lock` converted to a different type will use likely unintended monitor-based locking in `lock` statement.*
+
+## New errors
+
+- **CS9237**: *''yield return' should not be used in the body of a lock statement*
+- **CS9238**: *Cannot use 'yield return' in an 'unsafe' block*
+- **CS9239**: *The `&` operator cannot be used on parameters or local variables in iterator methods.*
+
+These errors indicate that your code violates safety rules because an iterator returns an element and resumes to generate the next element:
+
+- You can't `yield return` from inside a `lock` statement block. Doing so can cause deadlocks.
+- You can't `yield return` from an `unsafe` block. The context for an iterator creates a nested `safe` block within the enclosing `unsafe` block.
+- You can't use the `&` operator to take the address of a variable in an iterator method.
+
+You must update your code to remove the constructs that aren't allowed.
diff --git a/docs/csharp/language-reference/toc.yml b/docs/csharp/language-reference/toc.yml
index fad57332f76bd..6aeed9dc1e596 100644
--- a/docs/csharp/language-reference/toc.yml
+++ b/docs/csharp/language-reference/toc.yml
@@ -464,6 +464,9 @@ items:
       CS8351, CS8373, CS8374, CS8388, CS8977, CS9072, CS9077, CS9078, CS9079, CS9085, CS9086, CS9087, CS9089, CS9091, CS9092,
       CS9093, CS9094, CS9095, CS9096, CS9097, CS9101, CS9102, CS9104, CS9190, CS9191, CS9192, CS9193, CS9195, CS9196, CS9197,
       CS9198, CS9199, CS9200, CS9201
+  - name: Iterator methods
+    href: ./iterator-yield.md
+    displayName: yield return, yield break, CS9237, CS9238, CS9239
   - name: Params modifier
     href: ./compiler-messages/params-arrays.md
     displayName: >