Document advanced callback control features

[Copilot]

Four advanced callback control features (.When(), .For(), .Only(), .InParallel(), and invocation counter access) were implemented and tested but undocumented.

Changes

Added documentation for:

• Conditional Callbacks - .When(predicate) filters callback execution based on 0-indexed invocation count
• Frequency Control - .For(n) executes exactly n times, .Only(n) executes up to n times
• Parallel Callbacks - .InParallel() runs callback on every invocation regardless of setup order
• Invocation Counter - Callbacks can accept int count parameter to access invocation index

Example

// Conditional execution
mock.SetupMock.Method.Process(It.IsAny<string>())
    .Do(() => Console.WriteLine("Called!"))
    .When(count => count < 3);  // Only first 3 invocations (0-indexed)

// Frequency control
mock.SetupMock.Method.Process(It.IsAny<string>())
    .Do(() => Console.WriteLine("Limited"))
    .For(5);  // Exactly 5 times

// Invocation counter access
mock.SetupMock.Property.Value
    .OnGet.Do((int count, int value) => 
        Console.WriteLine($"Read #{count}, value: {value}"));

Documentation added to both README.md and Docs/pages/02-setup.md.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document advanced callback features</issue_title>
<issue_description>## Description

Several advanced callback control features are missing from the callback documentation.

Missing Documentation

• .When(Func<int, bool>) - Conditional callback execution
• .For(int times) - Execute callback N times
• .Only(int times) - Execute callback up to N times
• .InParallel() - Execute callback in parallel
• Invocation counter in callbacks (Action<int>)

Suggested Documentation

Expand the callback sections with subsections for:

1. Conditional Callbacks (.When())
2. Frequency Control (.For(), .Only())
3. Parallel Callbacks (.InParallel())
4. Invocation Counter

Conditional Callbacks

Execute callbacks conditionally based on invocation count:

sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
    .Do(() => Console.WriteLine("Called!"))
    .When(count => count <= 3);  // Only first 3 invocations

Frequency Control

Control how many times a callback executes:

// Execute exactly 5 times
sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
    .Do(() => Console.WriteLine("First 5 calls"))
    .For(5);

// Execute up to 3 times
sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
    .Do(() => Console.WriteLine("Up to 3 calls"))
    .Only(3);

Parallel Callbacks

Execute callbacks in parallel:

sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
    .Do(() => { /* parallel work */ })
    .InParallel();

Invocation Counter

Access the invocation counter in callbacks:

sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
    .Do((int count) => Console.WriteLine($"Call #{count}"));

sut.SetupMock.Property.TotalDispensed
    .OnGet.Do((int count, int value) => 
        Console.WriteLine($"Read #{count}, value: {value}"));
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

• Fixes Document advanced callback features #419

---

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

[vbreuss]

Obsolete by #430