Add documentation for using statements in iterators (#48071)

* Initial plan

* Add documentation about using statements in iterators with code example

Co-authored-by: BillWagner <[email protected]>

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: BillWagner <[email protected]>
Co-authored-by: Bill Wagner <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>

Author: 3 people

docs/csharp/language-reference/statements/snippets/yield/Program.cs

@@ -4,6 +4,8 @@
 GetEnumeratorExample.Example();
 Console.WriteLine();
 IteratorExecution();
+Console.WriteLine();
+UsingInIterator();
 
 static void YieldReturn()
 {
@@ -116,3 +118,39 @@ IEnumerable<int> ProduceEvenNumbers(int upto)
     // </IteratorExecution>
     Console.WriteLine();
 }
+
+static void UsingInIterator()
+{
+    // <UsingInIterator>
+    Console.WriteLine("=== Using in Iterator Example ===");
+    
+    // Demonstrate that using statements work correctly in iterators
+    foreach (string line in ReadLinesFromResource())
+    {
+        Console.WriteLine($"Read: {line}");
+        // Simulate processing only first two items
+        if (line == "Line 2") break;
+    }
+    
+    Console.WriteLine("Iteration stopped early - resource should still be disposed.");
+    
+    static IEnumerable<string> ReadLinesFromResource()
+    {
+        Console.WriteLine("Opening resource...");
+        using var resource = new StringWriter(); // Use StringWriter as a simple IDisposable
+        resource.WriteLine("Resource initialized");
+        
+        // These lines would typically come from the resource (e.g., file, database)
+        string[] lines = { "Line 1", "Line 2", "Line 3", "Line 4" };
+        
+        foreach (string line in lines)
+        {
+            Console.WriteLine($"About to yield: {line}");
+            yield return line;
+            Console.WriteLine($"Resumed after yielding: {line}");
+        }
+        
+        Console.WriteLine("Iterator completed - using block will dispose resource.");
+    }
+    // </UsingInIterator>
+}

docs/csharp/language-reference/statements/yield.md

@@ -40,6 +40,14 @@ You can't use the `yield` statements in:
 - [unsafe blocks](../keywords/unsafe.md). Before C# 13, `yield` was invalid in any method with an `unsafe` block. Beginning with C# 13, you can use `yield` in methods with `unsafe` blocks, but not in the `unsafe` block.
 - `yield return` and `yield break` can not be used in [catch](../statements/exception-handling-statements.md) and [finally](../statements/exception-handling-statements.md) blocks, or in [try](../statements/exception-handling-statements.md) blocks with a corresponding `catch` block. The `yield return` and `yield break` statements can be used in a `try` block with no `catch` blocks, only a `finally` block.
 
+## `using` statements in iterators
+
+You can use [`using` statements](using.md) in iterator methods. Since `using` statements are compiled into `try` blocks with `finally` clauses (and no `catch` blocks), they work correctly with iterators. The disposable resources are properly managed throughout the iterator's execution:
+
+:::code language="csharp" interactive="try-dotnet-method" source="snippets/yield/Program.cs" id="UsingInIterator":::
+
+As the preceding example shows, the resource acquired in the `using` statement remains available throughout the iterator's execution, even when the iterator suspends and resumes execution at `yield return` statements. The resource is disposed when the iterator completes (either by reaching the end or via `yield break`) or when the iterator itself is disposed (for example, when the caller breaks out of enumeration early).
+
 ## Execution of an iterator
 
 The call of an iterator doesn't execute it immediately, as the following example shows: