Addresses confusion about the relationship between try blocks and using statements in iterator methods by adding clear documentation and a working example.

Problem

Anonymous feedback indicated confusion about whether using blocks can be used inside iterator functions and whether they get auto-disposed after the first yield return. This is a common source of confusion since iterators have restrictions on try blocks with catch clauses.

Solution

Added a new section "Using statements in iterators" to the yield statement documentation that explains:

1. using statements work correctly in iterators because they compile to try/finally blocks without catch clauses
2. Resources persist throughout iterator execution - they are NOT disposed after the first yield return
3. Proper disposal occurs when the iterator completes or when the iterator itself is disposed (e.g., when caller breaks early)

Code Example

The documentation includes a practical example demonstrating:

static IEnumerable<string> ReadLinesFromResource()
{
    Console.WriteLine("Opening resource...");
    using var resource = new StringWriter(); // Resource managed by using statement
    resource.WriteLine("Resource initialized");
    
    string[] lines = { "Line 1", "Line 2", "Line 3", "Line 4" };
    
    foreach (string line in lines)
    {
        Console.WriteLine($"About to yield: {line}");
        yield return line; // Resource remains available across yields
        Console.WriteLine($"Resumed after yielding: {line}");
    }
    
    Console.WriteLine("Iterator completed - using block will dispose resource.");
}

This example shows that even when iteration breaks early, the resource is properly disposed when the iterator is cleaned up.

Technical Details

The documentation explains that this works because the C# compiler transforms using statements into try/finally blocks without catch clauses, which are explicitly permitted in iterator methods (unlike try blocks with catch clauses).

Fixes #45331.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.